feat(maestro): port layout system (tabs, splits, multiview) to React

Closes #249: layoutStore.ts wraps the existing layout.ts tree model
in Zustand, persisting to localStorage on a 400ms debounce and adding
boot reconciliation to prune leaves for sessions no longer live.
MultiView/TabBar/PaneContainer/PaneTitle render tabs, nested splits
with draggable dividers, drag-and-drop tab reordering, and dispatch
each pane to TerminalPane or StructuredPane by session view.

Preview mode (#251) and sidebar drag-to-dock stay out of scope here.
This commit is contained in:
Miguel Palhas
2026-09-09 01:21:37 +01:00
parent 52ae636dbb
commit 1b7ec1f54c
10 changed files with 1083 additions and 0 deletions
+162
View File
@@ -0,0 +1,162 @@
import { describe, expect, it, vi } from "vitest";
import { leaves } from "../layout.js";
import { createLayoutStore, type LayoutStoreOptions } from "./layoutStore.js";
function fakeScheduler() {
const timers = new Map<number, () => void>();
let id = 0;
return {
scheduler: {
setTimer: (fn: () => void) => {
const h = ++id;
timers.set(h, fn);
return h;
},
clearTimer: (h: number) => {
timers.delete(h);
},
},
flush() {
for (const fn of [...timers.values()]) fn();
timers.clear();
},
};
}
function store(opts: Partial<LayoutStoreOptions> = {}) {
return createLayoutStore({
load: () => null,
save: vi.fn(),
scheduler: fakeScheduler().scheduler,
...opts,
});
}
describe("layoutStore", () => {
it("boots with a single empty tab when nothing is persisted", () => {
const { layout } = store().getState();
expect(layout.tabs).toHaveLength(1);
expect(layout.tabs[0].root).toBeNull();
});
it("boots from a persisted layout when one loads", () => {
const persisted = store().getState().layout;
persisted.tabs[0].title = "Restored";
const s = store({ load: () => persisted });
expect(s.getState().layout.tabs[0].title).toBe("Restored");
});
it("openSession seeds the active tab from empty", () => {
const s = store();
s.getState().openSession("s1");
expect(leaves(s.getState().layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s1"]);
});
it("openSession focuses an already-open session instead of moving it", () => {
const s = store();
s.getState().openSession("s1");
s.getState().openSessionBeside("s2");
s.getState().openSession("s1");
const ids = leaves(s.getState().layout.tabs[0].root)
.map((l) => l.sessionId)
.sort();
expect(ids).toEqual(["s1", "s2"]);
});
it("openSessionBeside splits next to the focused pane instead of replacing it", () => {
const s = store();
s.getState().openSession("s1");
s.getState().openSessionBeside("s2");
expect(leaves(s.getState().layout.tabs[0].root)).toHaveLength(2);
});
it("openSessionBeside(newTab) opens its own tab", () => {
const s = store();
s.getState().openSession("s1");
s.getState().openSessionBeside("s2", { newTab: true });
expect(s.getState().layout.tabs).toHaveLength(2);
expect(leaves(s.getState().layout.tabs[1].root).map((l) => l.sessionId)).toEqual(["s2"]);
});
it("closeSession removes the pane and closes a tab left with nothing else", () => {
const s = store();
s.getState().openSession("s1");
s.getState().addTab();
s.getState().openSession("s2");
s.getState().closeSession("s2");
expect(s.getState().layout.tabs).toHaveLength(1);
expect(leaves(s.getState().layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s1"]);
});
it("splitFocused adds a leaf beside the given one and focuses it", () => {
const s = store();
s.getState().openSession("s1");
const first = leaves(s.getState().layout.tabs[0].root)[0].id;
s.getState().splitFocused(first, "row");
const tab = s.getState().layout.tabs[0];
expect(leaves(tab.root)).toHaveLength(2);
expect(tab.focusedLeafId).not.toBe(first);
});
it("closePane collapses the split back to the surviving leaf", () => {
const s = store();
s.getState().openSession("s1");
const first = leaves(s.getState().layout.tabs[0].root)[0].id;
s.getState().splitFocused(first, "row");
s.getState().closePane(first);
const remaining = leaves(s.getState().layout.tabs[0].root);
expect(remaining).toHaveLength(1);
expect(remaining[0].sessionId).toBeNull();
});
it("addTab/selectTab/closeTab manage the tab strip", () => {
const s = store();
s.getState().addTab();
expect(s.getState().layout.tabs).toHaveLength(2);
const [first, second] = s.getState().layout.tabs;
s.getState().selectTab(first.id);
expect(s.getState().layout.activeTabId).toBe(first.id);
s.getState().closeTab(second.id);
expect(s.getState().layout.tabs).toHaveLength(1);
});
it("reorderTab moves a tab to sit where another one is", () => {
const s = store();
s.getState().addTab();
s.getState().addTab();
const [a, b, c] = s.getState().layout.tabs;
s.getState().reorderTab(c.id, a.id);
expect(s.getState().layout.tabs.map((t) => t.id)).toEqual([c.id, a.id, b.id]);
});
it("reconcile drops leaves for sessions no longer live, and closes a tab left with nothing else", () => {
const s = store();
s.getState().openSession("s1");
s.getState().addTab();
s.getState().openSession("dead");
s.getState().reconcile(new Set(["s1"]));
const { layout } = s.getState();
expect(layout.tabs).toHaveLength(1);
expect(leaves(layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s1"]);
});
it("reconcile leaves an intentionally empty tab alone", () => {
const s = store();
s.getState().addTab();
s.getState().reconcile(new Set());
expect(s.getState().layout.tabs).toHaveLength(2);
});
it("debounces persistence to a single write once idle", () => {
const save = vi.fn();
const { scheduler, flush } = fakeScheduler();
const s = store({ save, scheduler });
s.getState().openSession("s1");
s.getState().openSessionBeside("s2");
expect(save).not.toHaveBeenCalled();
flush();
expect(save).toHaveBeenCalledTimes(1);
expect(save.mock.calls[0][0]).toBe(s.getState().layout);
});
});
+253
View File
@@ -0,0 +1,253 @@
// Zustand wrapper around ../layout.js's layout tree model (issue #249).
// Actions mutate the tree in place via layout.js's own functions, then
// re-wrap it so `useStore` selectors relying on referential equality notice.
import { create } from "zustand";
import {
activeTab,
addTab as addTabToLayout,
closeTab as closeTabInLayout,
emptyLayout,
equalizeRatios,
findLeaf,
leaves,
locateSession,
removeLeaf,
splitLeaf,
type Dir,
type Layout,
} from "../layout.js";
import { loadLayout, saveLayout } from "../persistence.js";
import type { Uuid } from "../types.js";
import type { Scheduler } from "./catalogStore.js";
const SAVE_DEBOUNCE_MS = 400;
const browserScheduler: Scheduler = {
setTimer: (fn, ms) => window.setTimeout(fn, ms),
clearTimer: (h) => window.clearTimeout(h),
};
export interface LayoutStoreOptions {
load?: () => Layout | null;
save?: (layout: Layout) => void;
scheduler?: Scheduler;
}
export interface LayoutState {
layout: Layout;
}
export interface LayoutActions {
/** Bring `sessionId` into view: focus it if already open, else fill the
* focused pane (VS-Code-style replace), or seed an empty tab. */
openSession(sessionId: Uuid): void;
/** Same, but never evicts a running pane: reuses an empty leaf or splits
* beside the focused one. `newTab` opens its own tab instead. */
openSessionBeside(sessionId: Uuid, opts?: { newTab?: boolean }): void;
/** Drop the pane showing `sessionId` (closed/killed elsewhere). */
closeSession(sessionId: Uuid): void;
splitFocused(leafId: string, dir: Dir): void;
closePane(leafId: string): void;
focusLeaf(leafId: string): void;
selectTab(tabId: string): void;
addTab(): void;
closeTab(tabId: string): void;
/** Tab-strip drag-and-drop reordering: moves `fromId` to sit where `toId`
* currently is. */
reorderTab(fromId: string, toId: string): void;
/** Persist whatever a divider drag left on a split's `ratio` — the drag
* itself mutates the node directly (same trade as the vanilla version),
* this just re-wraps and schedules the save. */
commitLayout(): void;
/** Boot reconciliation: drop every leaf whose session isn't in `liveIds`,
* and close any tab that held nothing else. A session killed while its
* tab was closed is pruned instead of leaving a pane that can only ever
* show a dead socket. Tabs that were already empty are left alone. */
reconcile(liveIds: ReadonlySet<Uuid>): void;
}
export type LayoutStore = LayoutState & LayoutActions;
export type LayoutStoreApi = ReturnType<typeof createLayoutStore>;
/** Builds an isolated layout store — load/save/scheduler are injectable
* (tests), or default to the real localStorage persistence.ts + browser
* timers. Same shape as {@link createCatalogStore}. */
export function createLayoutStore(opts: LayoutStoreOptions = {}) {
const load = opts.load ?? loadLayout;
const save = opts.save ?? saveLayout;
const scheduler = opts.scheduler ?? browserScheduler;
let saveTimer: number | null = null;
return create<LayoutStore>((set, get) => {
function touch(): void {
// A shallow clone, not the same reference back: `useStore` (and any
// other Object.is-based selector) needs the identity to change to
// notice a mutation made in place on the tree underneath.
set({ layout: { ...get().layout } });
}
function schedulePersist(): void {
if (saveTimer !== null) scheduler.clearTimer(saveTimer);
saveTimer = scheduler.setTimer(() => {
saveTimer = null;
save(get().layout);
}, SAVE_DEBOUNCE_MS);
}
function commit(): void {
touch();
schedulePersist();
}
function mutate(fn: (layout: Layout) => void): void {
fn(get().layout);
commit();
}
return {
layout: load() ?? emptyLayout(),
openSession(sessionId) {
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (loc) {
layout.activeTabId = loc.tab.id;
loc.tab.focusedLeafId = loc.leaf.id;
return;
}
const tab = activeTab(layout);
if (!tab.root) {
tab.focusedLeafId = splitLeaf(tab, "", sessionId, "row", true);
return;
}
const target = (tab.focusedLeafId && findLeaf(tab.root, tab.focusedLeafId)) || leaves(tab.root)[0];
target.sessionId = sessionId;
tab.focusedLeafId = target.id;
});
},
openSessionBeside(sessionId, placement) {
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (loc) {
layout.activeTabId = loc.tab.id;
loc.tab.focusedLeafId = loc.leaf.id;
return;
}
if (placement?.newTab) {
const fresh = addTabToLayout(layout);
fresh.focusedLeafId = splitLeaf(fresh, "", sessionId, "row", true);
return;
}
const tab = activeTab(layout);
if (!tab.root || !tab.focusedLeafId || !findLeaf(tab.root, tab.focusedLeafId)) {
tab.focusedLeafId = splitLeaf(tab, "", sessionId, "row", true);
return;
}
const target = findLeaf(tab.root, tab.focusedLeafId)!;
if (!target.sessionId) {
target.sessionId = sessionId;
} else {
tab.focusedLeafId = splitLeaf(tab, target.id, sessionId, "row", true);
equalizeRatios(tab.root);
}
});
},
closeSession(sessionId) {
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (!loc) return;
removeLeaf(loc.tab, loc.leaf.id);
if (loc.tab.focusedLeafId === loc.leaf.id) {
loc.tab.focusedLeafId = leaves(loc.tab.root)[0]?.id ?? null;
}
if (!loc.tab.root) closeTabInLayout(layout, loc.tab.id);
});
},
splitFocused(leafId, dir) {
mutate((layout) => {
const tab = activeTab(layout);
tab.focusedLeafId = splitLeaf(tab, leafId, null, dir, true);
equalizeRatios(tab.root);
});
},
closePane(leafId) {
mutate((layout) => {
const tab = activeTab(layout);
removeLeaf(tab, leafId);
if (tab.focusedLeafId === leafId) {
tab.focusedLeafId = leaves(tab.root)[0]?.id ?? null;
}
});
},
focusLeaf(leafId) {
mutate((layout) => {
const tab = activeTab(layout);
if (tab.focusedLeafId === leafId) return;
tab.focusedLeafId = leafId;
});
},
selectTab(tabId) {
mutate((layout) => {
if (layout.tabs.some((t) => t.id === tabId)) layout.activeTabId = tabId;
});
},
addTab() {
mutate((layout) => {
addTabToLayout(layout);
});
},
closeTab(tabId) {
mutate((layout) => {
closeTabInLayout(layout, tabId);
});
},
reorderTab(fromId, toId) {
mutate((layout) => {
if (fromId === toId) return;
const from = layout.tabs.findIndex((t) => t.id === fromId);
const to = layout.tabs.findIndex((t) => t.id === toId);
if (from < 0 || to < 0) return;
const [moved] = layout.tabs.splice(from, 1);
layout.tabs.splice(to, 0, moved);
});
},
commitLayout() {
commit();
},
reconcile(liveIds) {
mutate((layout) => {
const emptied: string[] = [];
for (const tab of [...layout.tabs]) {
let prunedAny = false;
for (const leaf of leaves(tab.root)) {
if (leaf.sessionId && !liveIds.has(leaf.sessionId)) {
removeLeaf(tab, leaf.id);
prunedAny = true;
}
}
if (!prunedAny) continue;
if (!tab.focusedLeafId || !findLeaf(tab.root, tab.focusedLeafId)) {
tab.focusedLeafId = leaves(tab.root)[0]?.id ?? null;
}
if (!tab.root) emptied.push(tab.id);
}
for (const id of emptied) closeTabInLayout(layout, id);
});
},
};
});
}