react-panel-layout 0.5.2 → 0.6.0

package/src/modules/panels/state/focus/logic.ts

@@ -0,0 +1,57 @@
+/**
+ * @file Focus and navigation helpers for panel-system.
+ */
+import type { GroupId, PanelSystemState } from "../types";
+import { collectGroupsInOrder } from "../tree/logic";
+
+export const setFocusedGroup = (state: PanelSystemState, groupId: GroupId): PanelSystemState => {
+  if (!state.groups[groupId]) {
+    throw new Error(`setFocusedGroup: group ${groupId} not found.`);
+  }
+  return { ...state, focusedGroupId: groupId };
+};
+
+export const focusGroupIndex = (state: PanelSystemState, index1Based: number): PanelSystemState => {
+  const idx = index1Based - 1;
+  const id = state.groupOrder[idx];
+  if (!id) {
+    return state;
+  }
+  return setFocusedGroup(state, id);
+};
+
+export const nextGroup = (state: PanelSystemState): PanelSystemState => {
+  const order = state.groupOrder;
+  const current = state.focusedGroupId;
+  if (!current) {
+    const first = order[0];
+    if (!first) {
+      return state;
+    }
+    return setFocusedGroup(state, first);
+  }
+  const idx = order.indexOf(current);
+  const next = order[(idx + 1) % order.length];
+  return setFocusedGroup(state, next);
+};
+
+export const prevGroup = (state: PanelSystemState): PanelSystemState => {
+  const order = state.groupOrder;
+  const current = state.focusedGroupId;
+  if (!current) {
+    const last = order[order.length - 1];
+    if (!last) {
+      return state;
+    }
+    return setFocusedGroup(state, last);
+  }
+  const idx = order.indexOf(current);
+  const prev = order[(idx - 1 + order.length) % order.length];
+  return setFocusedGroup(state, prev);
+};
+
+export const refreshGroupOrder = (state: PanelSystemState): PanelSystemState => {
+  const groupOrder = collectGroupsInOrder(state.tree);
+  return { ...state, groupOrder };
+};
+

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

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

package/src/modules/panels/state/groups/logic.ts

@@ -0,0 +1,105 @@
+/**
+ * @file Group and tab registry operations (pure, no tree logic).
+ */
+import type { GroupId, GroupModel, PanelId, PanelSystemState, TabDefinition } from "../types";
+
+export const createEmptyGroup = (id: GroupId): GroupModel => {
+  return { id, tabIds: [], tabs: [], activeTabId: null };
+};
+
+export const addTabToGroup = (state: PanelSystemState, groupId: GroupId, tab: TabDefinition, makeActive: boolean): PanelSystemState => {
+  const groups = { ...state.groups };
+  const group = groups[groupId];
+  if (!group) {
+    throw new Error(`Group ${groupId} does not exist.`);
+  }
+  const panels = { ...state.panels, [tab.id]: tab };
+  const tabIds = [...group.tabIds, tab.id];
+  const activeTabId = makeActive ? tab.id : group.activeTabId ?? tab.id;
+  const tabs = tabIds.map((id) => panels[id]);
+  const nextGroup: GroupModel = { ...group, tabIds, tabs, activeTabId };
+  groups[groupId] = nextGroup;
+  return { ...state, panels, groups };
+};
+
+export const removeTabFromGroup = (state: PanelSystemState, groupId: GroupId, tabId: PanelId): PanelSystemState => {
+  const groups = { ...state.groups };
+  const group = groups[groupId];
+  if (!group) {
+    throw new Error(`Group ${groupId} does not exist.`);
+  }
+  const tabIds = group.tabIds.filter((id) => id !== tabId);
+  const tabs = tabIds.map((id) => state.panels[id]);
+  const activeTabId = group.activeTabId === tabId ? (tabIds[0] ?? null) : group.activeTabId;
+  groups[groupId] = { ...group, tabIds, tabs, activeTabId };
+  return { ...state, groups };
+};
+
+export const moveTab = (state: PanelSystemState, fromGroupId: GroupId, toGroupId: GroupId, tabId: PanelId, makeActive: boolean): PanelSystemState => {
+  const from = state.groups[fromGroupId];
+  const to = state.groups[toGroupId];
+  if (!from || !to) {
+    throw new Error("moveTab: source or target group is missing.");
+  }
+  const groups = { ...state.groups };
+  const fromIds = from.tabIds.filter((id) => id !== tabId);
+  const toIds = [...to.tabIds.filter((id) => id !== tabId), tabId];
+  const fromActive = from.activeTabId === tabId ? (fromIds[0] ?? null) : from.activeTabId;
+  groups[fromGroupId] = { ...from, tabIds: fromIds, tabs: fromIds.map((id) => state.panels[id]), activeTabId: fromActive };
+  groups[toGroupId] = { ...to, tabIds: toIds, tabs: toIds.map((id) => state.panels[id]), activeTabId: makeActive ? tabId : to.activeTabId ?? tabId };
+  return { ...state, groups };
+};
+
+export const setActiveTab = (state: PanelSystemState, groupId: GroupId, tabId: PanelId): PanelSystemState => {
+  const group = state.groups[groupId];
+  if (!group) {
+    throw new Error(`setActiveTab: group ${groupId} not found.`);
+  }
+  if (!group.tabIds.some((id) => id === tabId)) {
+    throw new Error(`setActiveTab: tab ${tabId} not found in group ${groupId}.`);
+  }
+  const groups = { ...state.groups, [groupId]: { ...group, activeTabId: tabId } };
+  return { ...state, groups, focusedGroupId: groupId };
+};
+
+export const reorderTabWithinGroup = (state: PanelSystemState, groupId: GroupId, tabId: PanelId, toIndex: number): PanelSystemState => {
+  const group = state.groups[groupId];
+  if (!group) {
+    throw new Error(`reorderTabWithinGroup: group ${groupId} not found.`);
+  }
+  const currentIndex = group.tabIds.findIndex((id) => id === tabId);
+  if (currentIndex === -1) {
+    throw new Error(`reorderTabWithinGroup: tab ${tabId} not in group ${groupId}.`);
+  }
+  const boundedIndex = Math.max(0, Math.min(toIndex, group.tabIds.length - 1));
+  if (currentIndex === boundedIndex) {
+    return state;
+  }
+  const ids = group.tabIds.slice();
+  const [id] = ids.splice(currentIndex, 1);
+  ids.splice(boundedIndex, 0, id);
+  const tabs = ids.map((x) => state.panels[x]);
+  const groups = { ...state.groups, [groupId]: { ...group, tabIds: ids, tabs } };
+  return { ...state, groups };
+};
+
+export const addTabToGroupAtIndex = (
+  state: PanelSystemState,
+  groupId: GroupId,
+  tab: TabDefinition,
+  index: number,
+  makeActive: boolean,
+): PanelSystemState => {
+  const group = state.groups[groupId];
+  if (!group) {
+    throw new Error(`addTabToGroupAtIndex: group ${groupId} not found.`);
+  }
+  const panels = { ...state.panels, [tab.id]: tab };
+  const ids = group.tabIds.slice();
+  const boundedIndex = Math.max(0, Math.min(index, ids.length));
+  ids.splice(boundedIndex, 0, tab.id);
+  const tabs = ids.map((id) => panels[id]);
+  const activeTabId = makeActive ? tab.id : group.activeTabId ?? tab.id;
+  const groups = { ...state.groups, [groupId]: { ...group, tabIds: ids, tabs, activeTabId } };
+  return { ...state, panels, groups };
+};

package/src/modules/panels/state/splitLimits.spec.ts

@@ -0,0 +1,46 @@
+/**
+ * @file Tests for split limit helpers.
+ */
+import type { PanelTree } from "./types";
+import { measureSplitExtents, normalizeSplitLimits, canSplitDirection } from "./splitLimits";
+
+const group = (id: string): PanelTree => ({ type: "group", groupId: id });
+
+const horizontal = (a: PanelTree, b: PanelTree): PanelTree => ({ type: "split", direction: "horizontal", ratio: 0.5, a, b });
+const vertical = (a: PanelTree, b: PanelTree): PanelTree => ({ type: "split", direction: "vertical", ratio: 0.5, a, b });
+
+describe("split limit helpers", () => {
+  it("measures split extents per direction", () => {
+    const base = group("g1");
+    expect(measureSplitExtents(base)).toEqual({ horizontal: 1, vertical: 1 });
+
+    const withVertical = vertical(group("g1"), group("g2"));
+    expect(measureSplitExtents(withVertical)).toEqual({ horizontal: 1, vertical: 2 });
+
+    const nested = horizontal(withVertical, group("g3"));
+    expect(measureSplitExtents(nested)).toEqual({ horizontal: 2, vertical: 2 });
+
+    const deep = horizontal(vertical(group("g1"), group("g2")), vertical(group("g3"), group("g4")));
+    expect(measureSplitExtents(deep)).toEqual({ horizontal: 2, vertical: 2 });
+  });
+
+  it("prevents splits when limits would be exceeded", () => {
+    const limits = normalizeSplitLimits({ cols: 1, rows: 2 });
+    const base = group("g1");
+    expect(canSplitDirection(base, "g1", "vertical", limits)).toBe(false);
+    expect(canSplitDirection(base, "g1", "horizontal", limits)).toBe(true);
+
+    const withHorizontal = horizontal(group("g1"), group("g2"));
+    const verticalLimits = normalizeSplitLimits({ cols: 2 });
+    expect(canSplitDirection(withHorizontal, "g1", "horizontal", normalizeSplitLimits({ rows: 2 }))).toBe(false);
+    expect(canSplitDirection(withHorizontal, "g1", "vertical", verticalLimits)).toBe(true);
+  });
+
+  it("supports shorthand and legacy limit shapes", () => {
+    expect(normalizeSplitLimits(2)).toEqual({ rows: 2, cols: 2 });
+    expect(normalizeSplitLimits({ rows: 1 })).toEqual({ rows: 1, cols: Number.POSITIVE_INFINITY });
+    expect(normalizeSplitLimits({ cols: 3 })).toEqual({ rows: Number.POSITIVE_INFINITY, cols: 3 });
+    expect(normalizeSplitLimits({ maxHorizontal: 4 })).toEqual({ rows: 4, cols: Number.POSITIVE_INFINITY });
+    expect(normalizeSplitLimits({ maxVertical: 5 })).toEqual({ rows: Number.POSITIVE_INFINITY, cols: 5 });
+  });
+});

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

@@ -0,0 +1,90 @@
+/**
+ * @file Split-limit helpers for the panel system.
+ */
+import type { GroupId, PanelSplitLimits, PanelTree, SplitDirection } from "./types";
+import { splitLeaf, isGroup } from "./tree/logic";
+import { clampNumber, toFiniteNumberOr } from "../../../utils/math";
+
+export type NormalizedSplitLimits = {
+  rows: number;
+  cols: number;
+};
+
+const clampLimit = (value: number | undefined): number => {
+  const finite = toFiniteNumberOr(value, Number.POSITIVE_INFINITY);
+  return clampNumber(finite, 1);
+};
+
+const isObjectLimits = (limits: PanelSplitLimits): limits is Record<string, unknown> =>
+  typeof limits === "object" && limits !== null;
+
+const isRowsColsLimits = (limits: PanelSplitLimits): limits is { rows?: number; cols?: number } => {
+  if (!isObjectLimits(limits)) {
+    return false;
+  }
+  if ("rows" in limits) {
+    return true;
+  }
+  return "cols" in limits;
+};
+
+export const normalizeSplitLimits = (limits?: PanelSplitLimits): NormalizedSplitLimits => {
+  if (!limits) {
+    return {
+      rows: Number.POSITIVE_INFINITY,
+      cols: Number.POSITIVE_INFINITY,
+    };
+  }
+  if (typeof limits === "number") {
+    const normalized = clampLimit(limits);
+    return { rows: normalized, cols: normalized };
+  }
+  if (isRowsColsLimits(limits)) {
+    return {
+      rows: clampLimit(limits.rows),
+      cols: clampLimit(limits.cols),
+    };
+  }
+  const legacy = limits as { maxHorizontal?: number; maxVertical?: number };
+  return {
+    rows: clampLimit(legacy.maxHorizontal),
+    cols: clampLimit(legacy.maxVertical),
+  };
+};
+
+export type SplitExtents = {
+  horizontal: number;
+  vertical: number;
+};
+
+export const measureSplitExtents = (tree: PanelTree): SplitExtents => {
+  if (isGroup(tree)) {
+    return { horizontal: 1, vertical: 1 };
+  }
+  const a = measureSplitExtents(tree.a);
+  const b = measureSplitExtents(tree.b);
+  if (tree.direction === "horizontal") {
+    return { horizontal: a.horizontal + b.horizontal, vertical: Math.max(a.vertical, b.vertical) };
+  }
+  return { horizontal: Math.max(a.horizontal, b.horizontal), vertical: a.vertical + b.vertical };
+};
+
+const previewSplitTree = (tree: PanelTree, groupId: GroupId, direction: SplitDirection): PanelTree => {
+  const { tree: preview } = splitLeaf(tree, groupId, direction, () => "__preview__");
+  return preview;
+};
+
+export const canSplitDirection = (tree: PanelTree, groupId: GroupId, direction: SplitDirection, limits: NormalizedSplitLimits): boolean => {
+  if (!Number.isFinite(limits.rows) && !Number.isFinite(limits.cols)) {
+    return true;
+  }
+  const preview = previewSplitTree(tree, groupId, direction);
+  const extents = measureSplitExtents(preview);
+  if (extents.horizontal > limits.rows) {
+    return false;
+  }
+  if (extents.vertical > limits.cols) {
+    return false;
+  }
+  return true;
+};

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

@@ -0,0 +1,49 @@
+/**
+ * @file Unit tests for panel-system state operations (flattened path).
+ */
+import { buildInitialState, splitGroup, moveTab, focusGroupIndex, nextGroup, prevGroup } from "../index";
+import type { TabDefinition } from "./types";
+
+const makeTab = (id: string, title?: string): TabDefinition => ({ id, title: title ?? id, render: () => id });
+
+describe("panel-system state", () => {
+  it("initializes with one group and active tab", () => {
+    const tabs = [makeTab("a"), makeTab("b")];
+    const s = buildInitialState(tabs);
+    expect(s.groupOrder.length).toBe(1);
+    const gid = s.groupOrder[0];
+    expect(s.groups[gid].activeTabId).toBe("a");
+  });
+
+  it("splits the focused group vertically", () => {
+    const tabs = [makeTab("a")];
+    const s = buildInitialState(tabs);
+    const gid = s.groupOrder[0];
+    const s2 = splitGroup(s, gid, "vertical", () => "g_2");
+    expect(s2.groupOrder.length).toBe(2);
+    expect(s2.focusedGroupId).not.toBeNull();
+  });
+
+  it("moves a tab between groups and activates it", () => {
+    const tabs = [makeTab("a"), makeTab("b")];
+    const s1 = buildInitialState(tabs);
+    const gid = s1.groupOrder[0];
+    const s2 = splitGroup(s1, gid, "vertical", () => "g_2");
+    const dest = s2.groupOrder[1];
+    const s3 = moveTab(s2, gid, dest, "b", true);
+    expect(s3.groups[dest].activeTabId).toBe("b");
+    expect(s3.groups[gid].tabs.some((t) => t.id === "b")).toBe(false);
+  });
+
+  it("focus navigation works with index and cycling", () => {
+    const s1 = buildInitialState([makeTab("a")]);
+    const gid = s1.groupOrder[0];
+    const s2 = splitGroup(s1, gid, "vertical", () => "g_2");
+    const s3 = focusGroupIndex(s2, 2);
+    expect(s3.focusedGroupId).toBe(s3.groupOrder[1]);
+    const s4 = nextGroup(s3);
+    expect(s4.focusedGroupId).toBe(s4.groupOrder[0]);
+    const s5 = prevGroup(s4);
+    expect(s5.focusedGroupId).toBe(s5.groupOrder[1]);
+  });
+});

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

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

package/src/modules/panels/state/tree/logic.spec.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Unit tests for panel-system tree operations
+ */
+import type { PanelTree } from "../types";
+import { setSplitRatio } from "./logic";
+
+describe("panel-tree setSplitRatio", () => {
+  it("updates ratio and clamps to bounds", () => {
+    const tree: PanelTree = {
+      type: "split",
+      direction: "vertical",
+      ratio: 0.5,
+      a: { type: "group", groupId: "g_1" },
+      b: { type: "group", groupId: "g_2" },
+    };
+    const next = setSplitRatio(tree, [], 0.2);
+    if (next.type !== "split") {
+      throw new Error("expected split node");
+    }
+    expect(next.ratio).toBeCloseTo(0.2);
+
+    const over = setSplitRatio(tree, [], -10);
+    if (over.type !== "split") {
+      throw new Error("expected split node");
+    }
+    expect(over.ratio).toBeCloseTo(0.05);
+
+    const big = setSplitRatio(tree, [], 10);
+    if (big.type !== "split") {
+      throw new Error("expected split node");
+    }
+    expect(big.ratio).toBeCloseTo(0.95);
+  });
+});

package/src/modules/panels/state/tree/logic.ts

@@ -0,0 +1,138 @@
+/**
+ * @file Tree operations for panel-system (no registry or focus concerns).
+ */
+import type { GroupId, PanelTree, SplitDirection } from "../types";
+import { clampNumber } from "../../../../utils/math";
+
+export type PathSegment = "a" | "b";
+export type NodePath = PathSegment[];
+
+export const isGroup = (node: PanelTree): node is Extract<PanelTree, { type: "group" }> => {
+  return (node as { type: string }).type === "group";
+};
+
+export const collectGroupsInOrder = (node: PanelTree, acc: GroupId[] = []): GroupId[] => {
+  if (isGroup(node)) {
+    return [...acc, node.groupId];
+  }
+  const a = collectGroupsInOrder(node.a, acc);
+  return collectGroupsInOrder(node.b, a);
+};
+
+export const getAtPath = (root: PanelTree, path: NodePath): PanelTree => {
+  return path.reduce<PanelTree>((node, key) => (isGroup(node) ? node : node[key]), root);
+};
+
+export const setAtPath = (root: PanelTree, path: NodePath, value: PanelTree): PanelTree => {
+  if (path.length === 0) {
+    return value;
+  }
+  const [head, ...rest] = path;
+  if (isGroup(root)) {
+    // Invalid set; return original root
+    return root;
+  }
+  const next = head === "a" ? { ...root, a: setAtPath(root.a, rest, value) } : { ...root, b: setAtPath(root.b, rest, value) };
+  return next;
+};
+
+/**
+ * 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 const findLeafParent = (
+  node: PanelTree,
+  groupId: GroupId,
+  path: NodePath = [],
+): { splitPath: NodePath | null; side: PathSegment | null } | null => {
+  if (isGroup(node)) {
+    if (node.groupId === groupId) {
+      return { splitPath: null, side: null };
+    }
+    return null;
+  }
+  // Search child A; if it is the group leaf, current node is parent and side is 'a'
+  if (isGroup(node.a) && node.a.groupId === groupId) {
+    return { splitPath: path, side: "a" };
+  }
+  // Search child B
+  if (isGroup(node.b) && node.b.groupId === groupId) {
+    return { splitPath: path, side: "b" };
+  }
+  // Recurse deeper
+  const inA = findLeafParent(node.a, groupId, [...path, "a"]);
+  if (inA) {
+    return inA;
+  }
+  return findLeafParent(node.b, groupId, [...path, "b"]);
+};
+
+/**
+ * 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 const splitLeaf = (
+  root: PanelTree,
+  groupId: GroupId,
+  direction: SplitDirection,
+  createGroupId: () => GroupId,
+): { tree: PanelTree; newGroupId: GroupId } => {
+  const newGroupId = createGroupId();
+  const entry = findLeafParent(root, groupId);
+  const replacement: PanelTree = {
+    type: "split",
+    direction,
+    ratio: 0.5,
+    a: { type: "group", groupId },
+    b: { type: "group", groupId: newGroupId },
+  } as const;
+
+  if (!entry || entry.splitPath === null) {
+    // Root is the leaf
+    return { tree: replacement, newGroupId };
+  }
+  const parentPath = entry.splitPath;
+  const parent = getAtPath(root, parentPath);
+  if (isGroup(parent)) {
+    // Should not happen; guard for safety
+    return { tree: replacement, newGroupId };
+  }
+  const newParent = entry.side === "a" ? { ...parent, a: replacement } : { ...parent, b: replacement };
+  const newTree = setAtPath(root, parentPath, newParent);
+  return { tree: newTree, newGroupId };
+};
+
+/**
+ * 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 const closeLeaf = (root: PanelTree, groupId: GroupId): { tree: PanelTree; survivorGroupId: GroupId | null } => {
+  const entry = findLeafParent(root, groupId);
+  if (!entry || entry.splitPath === null) {
+    // Single-group root
+    return { tree: root, survivorGroupId: groupId };
+  }
+  const parentPath = entry.splitPath;
+  const parent = getAtPath(root, parentPath);
+  if (isGroup(parent)) {
+    return { tree: root, survivorGroupId: groupId };
+  }
+  const survivor = entry.side === "a" ? parent.b : parent.a;
+  const newTree = setAtPath(root, parentPath, survivor);
+  const survivorId = isGroup(survivor) ? survivor.groupId : collectGroupsInOrder(survivor)[0] ?? null;
+  return { tree: newTree, survivorGroupId: survivorId };
+};
+
+/**
+ * Set split ratio at a specific split node path. Clamps ratio into (0.05 .. 0.95) to avoid zero-size panes.
+ */
+export const setSplitRatio = (root: PanelTree, splitPath: NodePath, ratio: number): PanelTree => {
+  const node = getAtPath(root, splitPath);
+  if (isGroup(node)) {
+    return root;
+  }
+  const next = { ...node, ratio: clampNumber(ratio, 0.05, 0.95) } as PanelTree;
+  return setAtPath(root, splitPath, next);
+};