feat(maestro): port preview mode to React (#251)
Extends layoutStore with previewSession/commitPreview, mirroring multiview.ts's preview controller: a throwaway tab for a session no pane holds, byte-for-byte restore on end, and every real layout-changing action drops an active preview first. Never schedules a save while a preview is up. Adds usePreview, wrapping the store actions with previewSchedule.ts's 120ms leading-edge throttle, plus a touch guard and an immediate `end()` for real changes. MultiView/TabBar render the preview hue on the pane titlebar, canvas ring/chip, and the throwaway tab (dashed, unclickable).
This commit is contained in:
@@ -0,0 +1,174 @@
|
||||
// @vitest-environment happy-dom
|
||||
import { act, cleanup, render } from "@testing-library/react";
|
||||
import { afterEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
import { leaves } from "../layout.js";
|
||||
import { createLayoutStore, type LayoutStoreApi } from "../stores/layoutStore.js";
|
||||
import { usePreview, type UsePreviewResult } from "./usePreview.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();
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
/** Hand-driven clock + timer queue for the preview schedule's own throttle,
|
||||
* independent of the store's save-debounce scheduler above. */
|
||||
function fakeClock() {
|
||||
let now = 1_000;
|
||||
const timers = new Map<number, { at: number; fn: () => void }>();
|
||||
let handle = 1;
|
||||
return {
|
||||
now: () => now,
|
||||
setTimer: (fn: () => void, ms: number) => {
|
||||
const h = handle++;
|
||||
timers.set(h, { at: now + ms, fn });
|
||||
return h;
|
||||
},
|
||||
clearTimer: (h: number) => {
|
||||
timers.delete(h);
|
||||
},
|
||||
advance(ms: number) {
|
||||
now += ms;
|
||||
for (const [h, t] of [...timers]) {
|
||||
if (t.at <= now) {
|
||||
timers.delete(h);
|
||||
act(() => t.fn());
|
||||
}
|
||||
}
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function newStore(): LayoutStoreApi {
|
||||
return createLayoutStore({ load: () => null, save: vi.fn(), scheduler: fakeScheduler().scheduler });
|
||||
}
|
||||
|
||||
let controls: UsePreviewResult;
|
||||
|
||||
function Probe({ store, clock }: { store: LayoutStoreApi; clock: ReturnType<typeof fakeClock> }) {
|
||||
controls = usePreview({
|
||||
store,
|
||||
scheduleDeps: { now: clock.now, setTimer: clock.setTimer, clearTimer: clock.clearTimer },
|
||||
});
|
||||
return <div>{controls.previewedSessionId ?? "none"}</div>;
|
||||
}
|
||||
|
||||
afterEach(cleanup);
|
||||
|
||||
describe("usePreview", () => {
|
||||
it("shows the first preview immediately — no settling delay", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => controls.preview("s9"));
|
||||
expect(view.container.textContent).toBe("s9");
|
||||
expect(leaves(store.getState().layout.tabs[1]?.root ?? null).map((l) => l.sessionId)).toEqual(["s9"]);
|
||||
});
|
||||
|
||||
it("throttles a burst to one leading + one trailing pane swap", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => {
|
||||
controls.preview("s1");
|
||||
controls.preview("s8");
|
||||
controls.preview("s9");
|
||||
});
|
||||
expect(view.container.textContent).toBe("s1");
|
||||
clock.advance(120);
|
||||
expect(view.container.textContent).toBe("s9");
|
||||
});
|
||||
|
||||
it("touch never previews", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => controls.previewFromPointer("s9", "touch"));
|
||||
expect(view.container.textContent).toBe("none");
|
||||
expect(store.getState().preview).toBeNull();
|
||||
});
|
||||
|
||||
it("previewFromPointer still previews for mouse/pen", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => controls.previewFromPointer("s9", "mouse"));
|
||||
expect(view.container.textContent).toBe("s9");
|
||||
});
|
||||
|
||||
it("commit cancels a pending trailing preview and opens for real", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => {
|
||||
controls.preview("s1"); // leading edge: previews the already-open s1
|
||||
controls.preview("s9"); // queued, gap not elapsed yet
|
||||
controls.commit("s9");
|
||||
});
|
||||
expect(view.container.textContent).toBe("none"); // committed: no longer a preview
|
||||
expect(leaves(store.getState().layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s9"]);
|
||||
|
||||
clock.advance(120);
|
||||
// The cancelled trailing preview never fires.
|
||||
expect(view.container.textContent).toBe("none");
|
||||
});
|
||||
|
||||
it("end drops a preview immediately, bypassing the throttle", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => controls.preview("s9"));
|
||||
expect(view.container.textContent).toBe("s9");
|
||||
|
||||
act(() => controls.end());
|
||||
expect(view.container.textContent).toBe("none");
|
||||
expect(store.getState().layout.tabs).toHaveLength(1);
|
||||
});
|
||||
|
||||
it("cancels its pending trailing preview on unmount", () => {
|
||||
const store = newStore();
|
||||
store.getState().openSession("s1");
|
||||
store.getState().addTab();
|
||||
store.getState().openSession("s2"); // leading edge below will preview this, already on screen
|
||||
const clock = fakeClock();
|
||||
const view = render(<Probe store={store} clock={clock} />);
|
||||
|
||||
act(() => {
|
||||
controls.preview("s2"); // leading edge: fires now
|
||||
controls.preview("s9"); // queued trailing preview
|
||||
});
|
||||
expect(store.getState().preview?.sessionId).toBe("s2");
|
||||
view.unmount();
|
||||
clock.advance(120);
|
||||
// The queued trailing preview must not fire after unmount.
|
||||
expect(store.getState().preview?.sessionId).toBe("s2");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,81 @@
|
||||
// React port of previewSchedule.ts + multiview.ts's preview controller
|
||||
// (issue #251). Owns the throttled schedule, hands the layout store the
|
||||
// throttled result, and exposes the three ways a preview ends for real —
|
||||
// see docs/PREVIEW.md, the contract this mirrors.
|
||||
|
||||
import { useCallback, useEffect, useRef } from "react";
|
||||
import { useStore } from "zustand";
|
||||
|
||||
import { createPreviewSchedule, type PreviewScheduleDeps } from "../previewSchedule.js";
|
||||
import type { LayoutStore, LayoutStoreApi } from "../stores/layoutStore.js";
|
||||
import type { Uuid } from "../types.js";
|
||||
|
||||
export interface UsePreviewOptions {
|
||||
store: LayoutStoreApi;
|
||||
/** Test seam for the schedule's clock/timers. */
|
||||
scheduleDeps?: PreviewScheduleDeps;
|
||||
}
|
||||
|
||||
export interface UsePreviewResult {
|
||||
/** The session currently shown as a preview, or null. */
|
||||
previewedSessionId: Uuid | null;
|
||||
/** Throttled: show `sessionId` in the content pane, or `null` to put back
|
||||
* whatever was on screen (a highlight move, or the highlight leaving
|
||||
* every session). Never delayed on the leading edge. */
|
||||
preview(sessionId: Uuid | null): void;
|
||||
/** Pointer-hover entry point: touch has no hover, so a touch pointer never
|
||||
* previews (docs/PREVIEW.md). */
|
||||
previewFromPointer(sessionId: Uuid | null, pointerType: string): void;
|
||||
/** Choosing the previewed session — click/Enter on its row, click into its
|
||||
* pane, or handing it the keyboard (Tab). Keeps exactly what is on
|
||||
* screen: a throwaway tab becomes real, a focus move inside an existing
|
||||
* tab stands. Nothing moves a second time. */
|
||||
commit(sessionId: Uuid): void;
|
||||
/** Any other real change — opening the command bar, a dialog, navigating
|
||||
* away — ends a pending or active preview immediately, bypassing the
|
||||
* throttle. */
|
||||
end(): void;
|
||||
}
|
||||
|
||||
/** Preview state management (docs/PREVIEW.md): wraps the layout store's
|
||||
* `previewSession`/`commitPreview` with the 120ms pane-swap throttle so the
|
||||
* UI never has to schedule it by hand. */
|
||||
export function usePreview({ store, scheduleDeps }: UsePreviewOptions): UsePreviewResult {
|
||||
const previewedSessionId = useStore(store, (s: LayoutStore) => s.preview?.sessionId ?? null);
|
||||
|
||||
const scheduleRef = useRef<ReturnType<typeof createPreviewSchedule> | null>(null);
|
||||
if (!scheduleRef.current) {
|
||||
scheduleRef.current = createPreviewSchedule((id) => store.getState().previewSession(id), scheduleDeps);
|
||||
}
|
||||
useEffect(() => {
|
||||
const schedule = scheduleRef.current;
|
||||
return () => schedule?.cancel();
|
||||
}, []);
|
||||
|
||||
const preview = useCallback((sessionId: Uuid | null) => {
|
||||
scheduleRef.current?.(sessionId);
|
||||
}, []);
|
||||
|
||||
const previewFromPointer = useCallback(
|
||||
(sessionId: Uuid | null, pointerType: string) => {
|
||||
if (pointerType === "touch") return;
|
||||
preview(sessionId);
|
||||
},
|
||||
[preview],
|
||||
);
|
||||
|
||||
const commit = useCallback(
|
||||
(sessionId: Uuid) => {
|
||||
scheduleRef.current?.cancel();
|
||||
store.getState().openSession(sessionId);
|
||||
},
|
||||
[store],
|
||||
);
|
||||
|
||||
const end = useCallback(() => {
|
||||
scheduleRef.current?.cancel();
|
||||
store.getState().previewSession(null);
|
||||
}, [store]);
|
||||
|
||||
return { previewedSessionId, preview, previewFromPointer, commit, end };
|
||||
}
|
||||
Reference in New Issue
Block a user