Skip to content

Commit ef64323

Browse files
feat(studio): host apps can place overlays on the preview and restyle its stage (#4187)
* feat(studio): host apps can place overlays on the preview and restyle its stage * feat(studio): stage background also recolours the preview panel; document the host layer
1 parent b09619f commit ef64323

6 files changed

Lines changed: 127 additions & 2 deletions

File tree

‎packages/studio/src/components/EditorShell.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,10 @@ export interface EditorShellProps extends TimelineEditCallbackDeps {
6565
isGestureRecording?: boolean;
6666
recordingState?: GestureRecordingState;
6767
onToggleRecording?: () => void;
68+
/**
69+
* Host layer over the preview, positioned with `usePreviewCompositionRect`. Hidden in
70+
* fullscreen and during a block preview; below the selection overlay past z-index 10.
71+
*/
6872
gestureOverlay?: ReactNode;
6973
}
7074

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
// @vitest-environment happy-dom
2+
3+
import { act, useRef } from "react";
4+
import { createRoot } from "react-dom/client";
5+
import { afterEach, describe, expect, it } from "vitest";
6+
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
7+
import {
8+
usePreviewCompositionRect,
9+
type PreviewCompositionRect,
10+
} from "./usePreviewCompositionRect";
11+
12+
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
13+
14+
afterEach(() => {
15+
usePreviewIframeStore.getState().setIframe(null);
16+
document.body.innerHTML = "";
17+
});
18+
19+
function boxed<T extends HTMLElement>(el: T, box: [number, number, number, number]): T {
20+
const [left, top, width, height] = box;
21+
el.getBoundingClientRect = () => new DOMRect(left, top, width, height);
22+
return el;
23+
}
24+
25+
function mountProbe() {
26+
let rect: PreviewCompositionRect | undefined;
27+
function Probe() {
28+
const ref = useRef<HTMLDivElement>(null);
29+
rect = usePreviewCompositionRect(ref);
30+
return (
31+
<div
32+
ref={(el) => {
33+
ref.current = el;
34+
if (el) boxed(el, [10, 20, 1000, 600]);
35+
}}
36+
/>
37+
);
38+
}
39+
const host = document.createElement("div");
40+
document.body.append(host);
41+
act(() => createRoot(host).render(<Probe />));
42+
return () => rect;
43+
}
44+
45+
function compositionFrame(box: [number, number, number, number], width: number, height: number) {
46+
const iframe = boxed(document.createElement("iframe"), box);
47+
document.body.append(iframe);
48+
const root = iframe.contentDocument?.createElement("div");
49+
root?.setAttribute("data-composition-id", "main");
50+
root?.setAttribute("data-width", String(width));
51+
root?.setAttribute("data-height", String(height));
52+
if (root) iframe.contentDocument?.body.append(root);
53+
return iframe;
54+
}
55+
56+
const settle = () => new Promise((r) => setTimeout(r, 400));
57+
58+
describe("usePreviewCompositionRect", () => {
59+
it("reports the live preview iframe's box relative to the overlay, scaled to the composition", async () => {
60+
const read = mountProbe();
61+
const iframe = compositionFrame([110, 70, 960, 540], 1920, 1080);
62+
await act(async () => {
63+
usePreviewIframeStore.getState().setIframe(iframe);
64+
await settle();
65+
});
66+
expect(read()).toEqual({
67+
left: 100,
68+
top: 50,
69+
width: 960,
70+
height: 540,
71+
scaleX: 0.5,
72+
scaleY: 0.5,
73+
});
74+
});
75+
76+
it("follows the iframe when a reload replaces it", async () => {
77+
const read = mountProbe();
78+
await act(async () => {
79+
usePreviewIframeStore.getState().setIframe(compositionFrame([110, 70, 960, 540], 1920, 1080));
80+
await settle();
81+
});
82+
await act(async () => {
83+
usePreviewIframeStore.getState().setIframe(compositionFrame([60, 40, 500, 500], 1000, 1000));
84+
await settle();
85+
});
86+
expect(read()).toEqual({
87+
left: 50,
88+
top: 20,
89+
width: 500,
90+
height: 500,
91+
scaleX: 0.5,
92+
scaleY: 0.5,
93+
});
94+
});
95+
});
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import { useMemo, type RefObject } from "react";
2+
import { usePreviewIframeStore } from "../../player/store/previewIframeStore";
3+
import { useDomEditCompositionRect } from "./useDomEditCompositionRect";
4+
5+
export type { DomEditCompositionRect as PreviewCompositionRect } from "./useDomEditCompositionRect";
6+
7+
/**
8+
* Where the composition sits inside `overlayRef`, in overlay pixels, plus the scale from
9+
* composition units to pixels. Follows the live preview iframe across reloads.
10+
*/
11+
export function usePreviewCompositionRect(overlayRef: RefObject<HTMLDivElement | null>) {
12+
const iframeRef = useMemo<RefObject<HTMLIFrameElement | null>>(
13+
() => ({
14+
get current() {
15+
return usePreviewIframeStore.getState().iframe;
16+
},
17+
}),
18+
[],
19+
);
20+
return useDomEditCompositionRect({ iframeRef, overlayRef });
21+
}

‎packages/studio/src/components/nle/NLEPreview.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -442,7 +442,7 @@ export const NLEPreview = memo(function NLEPreview({
442442
<div className="flex flex-col h-full min-h-0">
443443
<div
444444
ref={viewportRef}
445-
className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-neutral-950"
445+
className="relative flex-1 flex items-center justify-center p-2 overflow-hidden min-h-0 outline-hidden focus:ring-1 focus:ring-studio-accent/40 bg-[var(--studio-preview-bg,var(--color-neutral-950))]"
446446
tabIndex={0}
447447
aria-label="Composition preview"
448448
>

‎packages/studio/src/components/nle/PreviewPane.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ export function PreviewPane({
110110
ref={containerRef}
111111
// Panel chrome (rounded border) is dropped in fullscreen so the preview
112112
// fills the screen edge-to-edge.
113-
className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-neutral-950 ${
113+
className={`flex-1 min-h-0 flex flex-col overflow-hidden bg-[var(--studio-preview-bg,var(--color-neutral-950))] ${
114114
isFullscreen ? "" : "rounded-lg border border-neutral-800/50"
115115
}`}
116116
data-studio-fullscreen-target=""

‎packages/studio/src/index.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ export type { ToggleProps } from "./components/ui/Toggle";
3030

3131
// NLE Layout
3232
export { EditorShell } from "./components/EditorShell";
33+
export type { EditorShellProps } from "./components/EditorShell";
3334
export { NLEPreview } from "./components/nle/NLEPreview";
3435
export { CompositionBreadcrumb } from "./components/nle/CompositionBreadcrumb";
3536
export type { CompositionLevel } from "./components/nle/CompositionBreadcrumb";
@@ -49,6 +50,10 @@ export {
4950
} from "./player";
5051
export type { TimelineElement } from "./player";
5152

53+
// Host overlays: draw over the preview in composition coordinates (see EditorShellProps.gestureOverlay)
54+
export { usePreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
55+
export type { PreviewCompositionRect } from "./components/editor/usePreviewCompositionRect";
56+
5257
// Editor
5358
export { SourceEditor } from "./components/editor/SourceEditor";
5459
export { PropertyPanel } from "./components/editor/PropertyPanel";

0 commit comments

Comments
 (0)