feat(studio): improve element picker cancellation feedback (#6900)

This commit is contained in:
Muzzy5150
2026-11-07 00:10:08 +00:00
committed by GitHub
parent a4a84deec5
commit f004622a6b
9 changed files with 911 additions and 51 deletions
+5
View File
@@ -87,6 +87,11 @@ Peer dependencies are React 19, React DOM 19, and Zustand 4 or 5.
The package also exports `CompositionLevel`, `TimelineElement`, `PickedElement`,
and `PatchOperation`.
`useElementPicker` remembers the current selection while inspection is active.
Press Escape in either Studio or the preview to cancel and restore that selection. The
hovered target is identified beside the preview as `tag#id`, `tag.class`, or the
tag name alone.
## How Studio stays connected to a project
1. Studio loads the composition in an iframe with the HyperFrames runtime.
@@ -7,6 +7,7 @@ export type HyperframePickerBoundingBox = {
export type HyperframePickerElementInfo = {
id: string | null;
className?: string | null;
tagName: string;
selector: string;
label: string;
+38
View File
@@ -155,6 +155,16 @@ describe("createPickerModule", () => {
expect(candidatesUnder(() => [long], "label")).toEqual([`${"x".repeat(54)}😀…`]);
});
it("includes the element classes needed by host hover identifiers", () => {
const picker = createPickerModule({ postMessage: createMockPostMessage() });
picker.installPickerApi();
const card = document.createElement("div");
card.className = "title featured";
document.body.appendChild(card);
expect(candidatesUnder(() => [card], "className")).toEqual(["title featured"]);
});
it("getCandidatesAtPoint returns empty for invalid coords", () => {
const picker = createPickerModule({ postMessage: createMockPostMessage() });
picker.installPickerApi();
@@ -466,6 +476,34 @@ describe("createPickerModule", () => {
restore();
}
});
it("refreshes hovered geometry while the preview scrolls and stops after disable", () => {
const postMessage = createMockPostMessage();
const picker = createPickerModule({ postMessage });
document.body.innerHTML = `<h1 id="title">Hi</h1>`;
let top = 10;
at("title").getBoundingClientRect = () => new DOMRect(20, top, 100, 40);
const restore = emulateHitTest(() => [at("title")]);
try {
picker.enablePickMode();
move();
top = 30;
document.dispatchEvent(new Event("scroll"));
const hovered = () =>
postMessage.mock.calls
.map(([message]) => message)
.filter((message) => message.type === "element-hovered");
expect(hovered().at(-1)?.elementInfo.boundingBox.y).toBe(30);
picker.disablePickMode();
const countAfterDisable = hovered().length;
document.dispatchEvent(new Event("scroll"));
expect(hovered()).toHaveLength(countAfterDisable);
} finally {
picker.disablePickMode();
restore();
}
});
});
describe("picks what is drawn under the pointer", () => {
+12
View File
@@ -303,6 +303,7 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
const htmlEl = el as HTMLElement;
return {
id: htmlEl.id || null,
className: el.getAttribute("class") || null,
tagName: el.tagName.toLowerCase(),
selector: buildElementSelector(el),
label: buildElementLabel(el),
@@ -343,6 +344,13 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
}
function onPickViewportChange(): void {
if (!pickModeActive || !pickModeHighlightEl?.isConnected) return;
const info = extractElementInfo(pickModeHighlightEl);
setLastHoveredInfo(info);
deps.postMessage({ source: "hf-preview", type: "element-hovered", elementInfo: info });
}
function onPickClick(event: MouseEvent): void {
if (!pickModeActive) return;
event.preventDefault();
@@ -379,6 +387,8 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
document.addEventListener("mousemove", onPickMouseMove, true);
document.addEventListener("click", onPickClick, true);
document.addEventListener("keydown", onPickKeyDown, true);
document.addEventListener("scroll", onPickViewportChange, true);
window.addEventListener("resize", onPickViewportChange);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: true, timestamp: Date.now() });
}
@@ -397,6 +407,8 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
document.removeEventListener("mousemove", onPickMouseMove, true);
document.removeEventListener("click", onPickClick, true);
document.removeEventListener("keydown", onPickKeyDown, true);
document.removeEventListener("scroll", onPickViewportChange, true);
window.removeEventListener("resize", onPickViewportChange);
emitPickerRuntimeEvent("hyperframe:picker:mode", { isPickMode: false, timestamp: Date.now() });
}
@@ -0,0 +1,85 @@
// @vitest-environment happy-dom
import { build } from "esbuild";
import { join } from "node:path";
import { afterEach, expect, it, vi } from "vitest";
import { closeTestChrome, launchTestChrome } from "../../tests/chromeTestUtils";
vi.setConfig({ testTimeout: 60_000 });
let browser: Awaited<ReturnType<typeof launchTestChrome>> | undefined;
afterEach(async () => {
await closeTestChrome(browser);
browser = undefined;
});
it("keeps the hover label readable inside a transformed preview without taking pointer input", async () => {
const bundle = await build({
entryPoints: [join(import.meta.dirname, "elementPickerHoverLabel.ts")],
bundle: true,
format: "iife",
globalName: "PickerHoverLabel",
platform: "browser",
write: false,
});
browser = await launchTestChrome();
const page = await browser.newPage();
await page.setViewport({ width: 900, height: 600 });
await page.setContent(`<!doctype html><style>
:root {
--color-studio-accent: #6ee7b7;
--color-studio-bg: #18181b;
--color-studio-text: #fafafa;
--shadow-popover: 0 2px 8px #0008;
}
body { margin: 40px; }
iframe { width: 320px; height: 180px; transform: scale(1.5); transform-origin: top left; }
</style><iframe id="preview"></iframe>`);
await page.addScriptTag({ content: bundle.outputFiles[0]?.text });
const result = await page.evaluate(() => {
const preview = document.querySelector<HTMLIFrameElement>("#preview");
if (!preview) throw new Error("preview iframe missing");
const api = (
window as typeof window & {
PickerHoverLabel: {
createElementPickerHoverLabel(): {
show(
info: {
id: string;
tagName: string;
boundingBox: { x: number; y: number; width: number; height: number };
},
iframe: HTMLIFrameElement,
): void;
};
};
}
).PickerHoverLabel.createElementPickerHoverLabel();
api.show(
{
id: "hero-title",
tagName: "h1",
boundingBox: { x: 270, y: 24, width: 40, height: 30 },
},
preview,
);
const label = document.querySelector<HTMLElement>("[data-hf-picker-hover-label]");
if (!label) throw new Error("hover label missing");
const labelRect = label.getBoundingClientRect();
const previewRect = preview.getBoundingClientRect();
return {
text: label.textContent,
pointerEvents: getComputedStyle(label).pointerEvents,
insidePreview: labelRect.left >= previewRect.left && labelRect.right <= previewRect.right,
insideViewport: labelRect.left >= 0 && labelRect.right <= innerWidth,
};
});
expect(result).toEqual({
text: "h1#hero-title",
pointerEvents: "none",
insidePreview: true,
insideViewport: true,
});
});
@@ -0,0 +1,106 @@
// @vitest-environment jsdom
import { afterEach, describe, expect, it } from "vitest";
import {
createElementPickerHoverLabel,
elementPickerLabelPosition,
formatElementPickerIdentifier,
} from "./elementPickerHoverLabel";
afterEach(() => {
document.body.innerHTML = "";
});
describe("formatElementPickerIdentifier", () => {
const box = { x: 0, y: 0, width: 10, height: 10 };
it.each([
[{ tagName: "H1", id: "hero-title", className: "headline", boundingBox: box }, "h1#hero-title"],
[{ tagName: "DIV", id: null, className: "title featured", boundingBox: box }, "div.title"],
[{ tagName: "SPAN", id: null, className: null, boundingBox: box }, "span"],
[
{
tagName: "P",
id: null,
className: "__hf-pick-highlight caption",
boundingBox: box,
},
"p.caption",
],
])("formats %j as %s", (info, expected) => {
expect(formatElementPickerIdentifier(info)).toBe(expected);
});
it("bounds long and unusual identifiers without interpreting markup", () => {
const identifier = formatElementPickerIdentifier({
tagName: "DIV",
id: `<img onerror=alert(1)>${"x".repeat(100)}`,
className: null,
boundingBox: box,
});
expect(Array.from(identifier)).toHaveLength(72);
expect(identifier).toMatch(/^div#<img onerror=alert\(1\)>/);
expect(identifier.endsWith("…")).toBe(true);
});
});
describe("elementPickerLabelPosition", () => {
it("maps iframe coordinates through zoom and flips inside the visible frame", () => {
expect(
elementPickerLabelPosition({
iframeRect: { left: 100, top: 50, right: 500, bottom: 250, width: 400, height: 200 },
iframeWidth: 200,
iframeHeight: 100,
elementBox: { x: 180, y: 90, width: 20, height: 10 },
labelWidth: 80,
labelHeight: 20,
viewportWidth: 800,
viewportHeight: 600,
}),
).toEqual({ left: 374, top: 230 });
});
it("clamps a partly offscreen preview to the usable viewport", () => {
expect(
elementPickerLabelPosition({
iframeRect: { left: -50, top: -20, right: 150, bottom: 80, width: 200, height: 100 },
iframeWidth: 200,
iframeHeight: 100,
elementBox: { x: 0, y: 0, width: 5, height: 5 },
labelWidth: 80,
labelHeight: 20,
viewportWidth: 100,
viewportHeight: 60,
}),
).toEqual({ left: 0, top: 0 });
});
});
describe("createElementPickerHoverLabel", () => {
it("renders plain text without intercepting pointer input and removes itself", () => {
const iframe = document.body.appendChild(document.createElement("iframe"));
Object.defineProperties(iframe, {
clientWidth: { configurable: true, value: 200 },
clientHeight: { configurable: true, value: 100 },
});
iframe.getBoundingClientRect = () => new DOMRect(20, 30, 400, 200);
const hoverLabel = createElementPickerHoverLabel();
hoverLabel.show(
{
tagName: "div",
id: "<b>not markup</b>",
className: null,
boundingBox: { x: 10, y: 20, width: 30, height: 40 },
},
iframe,
);
const label = document.querySelector<HTMLElement>("[data-hf-picker-hover-label]");
expect(label?.textContent).toBe("div#<b>not markup</b>");
expect(label?.querySelector("b")).toBeNull();
expect(label?.style.pointerEvents).toBe("none");
expect(label?.style.position).toBe("fixed");
hoverLabel.dispose();
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
});
});
@@ -0,0 +1,173 @@
import type { HyperframePickerBoundingBox } from "@hyperframes/core";
const LABEL_GAP_PX = 6;
const LABEL_MAX_CHARS = 72;
export interface ElementPickerHoverInfo {
id: string | null;
className?: string | null;
tagName: string;
boundingBox: HyperframePickerBoundingBox;
}
export function formatElementPickerIdentifier(info: ElementPickerHoverInfo): string {
const tag = info.tagName.trim().toLowerCase() || "element";
const id = info.id?.trim();
const firstClass = info.className
?.split(/\s+/)
.find((name) => name.length > 0 && !name.startsWith("__hf-"));
const identifier = id ? `${tag}#${id}` : firstClass ? `${tag}.${firstClass}` : tag;
const characters = Array.from(identifier);
return characters.length > LABEL_MAX_CHARS
? `${characters.slice(0, LABEL_MAX_CHARS - 1).join("")}…`
: identifier;
}
interface LabelPositionInput {
iframeRect: Pick<DOMRect, "left" | "top" | "right" | "bottom" | "width" | "height">;
iframeWidth: number;
iframeHeight: number;
elementBox: HyperframePickerBoundingBox;
labelWidth: number;
labelHeight: number;
viewportWidth: number;
viewportHeight: number;
}
export function elementPickerLabelPosition(input: LabelPositionInput): {
left: number;
top: number;
} {
const scaleX = input.iframeWidth > 0 ? input.iframeRect.width / input.iframeWidth : 1;
const scaleY = input.iframeHeight > 0 ? input.iframeRect.height / input.iframeHeight : 1;
const elementLeft = input.iframeRect.left + input.elementBox.x * scaleX;
const elementRight = elementLeft + input.elementBox.width * scaleX;
const elementTop = input.iframeRect.top + input.elementBox.y * scaleY;
const minLeft = Math.max(0, input.iframeRect.left);
const maxRight = Math.min(input.viewportWidth, input.iframeRect.right);
const minTop = Math.max(0, input.iframeRect.top);
const maxBottom = Math.min(input.viewportHeight, input.iframeRect.bottom);
const maxLeft = Math.max(minLeft, maxRight - input.labelWidth);
const maxTop = Math.max(minTop, maxBottom - input.labelHeight);
const besideRight = elementRight + LABEL_GAP_PX;
const besideLeft = elementLeft - input.labelWidth - LABEL_GAP_PX;
const preferredLeft = besideRight + input.labelWidth <= maxRight ? besideRight : besideLeft;
return {
left: Math.min(maxLeft, Math.max(minLeft, preferredLeft)),
top: Math.min(maxTop, Math.max(minTop, elementTop)),
};
}
export interface ElementPickerHoverLabel {
show: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void;
clear: () => void;
dispose: () => void;
}
function firstPositive(values: number[]): number {
return values.find((value) => value > 0) ?? 0;
}
function iframeLayoutSize(
iframe: HTMLIFrameElement,
rect: DOMRect,
): {
width: number;
height: number;
} {
return {
width: firstPositive([iframe.clientWidth, iframe.offsetWidth, rect.width]),
height: firstPositive([iframe.clientHeight, iframe.offsetHeight, rect.height]),
};
}
function viewportSize(doc: Document): { width: number; height: number } {
const view = doc.defaultView;
return view
? { width: view.innerWidth, height: view.innerHeight }
: { width: doc.documentElement.clientWidth, height: doc.documentElement.clientHeight };
}
export function createElementPickerHoverLabel(doc: Document = document): ElementPickerHoverLabel {
const label = doc.createElement("div");
label.dataset.hfPickerHoverLabel = "";
label.ariaHidden = "true";
Object.assign(label.style, {
position: "fixed",
zIndex: "100",
pointerEvents: "none",
maxWidth: "220px",
overflow: "hidden",
textOverflow: "ellipsis",
whiteSpace: "nowrap",
border: "1px solid color-mix(in oklab, var(--color-studio-accent) 55%, transparent)",
borderRadius: "4px",
background: "var(--color-studio-bg)",
color: "var(--color-studio-text)",
boxShadow: "var(--shadow-popover)",
padding: "2px 6px",
fontFamily: "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace",
fontSize: "10px",
lineHeight: "16px",
});
let current: { info: ElementPickerHoverInfo; iframe: HTMLIFrameElement } | null = null;
let animationFrame: number | null = null;
const draw = () => {
if (!current || !current.iframe.isConnected) {
clear();
return;
}
if (!label.isConnected) doc.body.appendChild(label);
label.textContent = formatElementPickerIdentifier(current.info);
const iframeRect = current.iframe.getBoundingClientRect();
const labelRect = label.getBoundingClientRect();
const iframeSize = iframeLayoutSize(current.iframe, iframeRect);
const viewport = viewportSize(doc);
const position = elementPickerLabelPosition({
iframeRect,
iframeWidth: iframeSize.width,
iframeHeight: iframeSize.height,
elementBox: current.info.boundingBox,
labelWidth: labelRect.width,
labelHeight: labelRect.height,
viewportWidth: viewport.width,
viewportHeight: viewport.height,
});
label.style.left = `${position.left}px`;
label.style.top = `${position.top}px`;
};
const tick = () => {
animationFrame = null;
draw();
if (current && doc.defaultView) animationFrame = doc.defaultView.requestAnimationFrame(tick);
};
const startTracking = () => {
if (animationFrame === null && doc.defaultView) {
animationFrame = doc.defaultView.requestAnimationFrame(tick);
}
};
function clear(): void {
current = null;
if (animationFrame !== null && doc.defaultView) {
doc.defaultView.cancelAnimationFrame(animationFrame);
animationFrame = null;
}
label.remove();
}
return {
show(info, iframe) {
current = { info, iframe };
draw();
startTracking();
},
clear,
dispose: clear,
};
}
@@ -3,7 +3,7 @@ import React, { act, useState } from "react";
import { createRoot, type Root } from "react-dom/client";
import { ensureHfIds } from "@hyperframes/parsers/hf-ids";
import { runtimeProtocolMetadata } from "@hyperframes/core/runtime/protocol";
import { afterEach, describe, expect, it } from "vitest";
import { afterEach, describe, expect, it, vi } from "vitest";
import { useElementPicker } from "./useElementPicker";
// As the host leaves it on disk: hf-ids pinned, no element ids.
@@ -17,6 +17,7 @@ afterEach(() => {
act(() => root?.unmount());
root = null;
document.body.innerHTML = "";
vi.restoreAllMocks();
});
// The runtime's element-picked message, posted by `from`.
@@ -35,6 +36,33 @@ const picked = (from: Window | null, selector: string) =>
);
});
const pickerMessage = (from: Window | null, data: Record<string, unknown>) =>
act(() => {
window.dispatchEvent(
new MessageEvent("message", {
source: from,
data: {
source: "hf-preview",
...data,
...runtimeProtocolMetadata(30),
},
}),
);
});
const hoverInfo = (overrides: Record<string, unknown> = {}) => ({
id: null,
className: "title",
tagName: "div",
selector: "div.title",
label: "Title",
boundingBox: { x: 20, y: 30, width: 100, height: 40 },
textContent: "Title",
src: null,
dataAttributes: {},
...overrides,
});
// The preview page: the saved markup plus what the runtime adds to it.
function mountPreview(mounted = ""): HTMLIFrameElement {
const iframe = document.createElement("iframe");
@@ -80,12 +108,150 @@ function mountPicker(
picked(iframe.contentWindow, selector);
const picker = () => api as ReturnType<typeof useElementPicker>;
return {
iframe,
picker,
synced,
setHostFiles: (next: Record<string, string>) => act(() => setHostFiles(next)),
};
}
describe("pick mode cancellation and hover feedback", () => {
it("cancels pick mode when Escape is pressed with Studio focus", () => {
const { picker } = mountPicker({ "index.html": SAVED });
act(() => picker().enablePick());
act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
expect(picker().isPickMode).toBe(false);
});
it("shows the hovered element identifier beside the preview", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
act(() => picker().enablePick());
pickerMessage(iframe.contentWindow, {
type: "element-hovered",
elementInfo: hoverInfo(),
});
expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div.title");
});
it("restores the element selected before pick mode began when cancelled", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
expect(picker().pickedElement?.selector).toBe("h1");
act(() => picker().enablePick());
pickerMessage(iframe.contentWindow, {
type: "element-pick-candidates",
candidates: [{ selector: "div.candidate", tagName: "div" }],
selectedIndex: 0,
point: { x: 1, y: 1 },
});
expect(picker().pickedElement?.selector).toBe("div.candidate");
act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
expect(picker().pickedElement?.selector).toBe("h1");
});
it("restores the previous selection when Escape comes from the preview runtime", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
act(() => picker().enablePick());
pickerMessage(iframe.contentWindow, {
type: "element-pick-candidates",
candidates: [{ selector: "div.candidate", tagName: "div" }],
selectedIndex: 0,
point: { x: 1, y: 1 },
});
pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
expect(picker().isPickMode).toBe(false);
expect(picker().pickedElement?.selector).toBe("h1");
});
it("ignores Escape while inactive and where an editor owns it", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
const frameWindow = iframe.contentWindow;
if (!frameWindow) throw new Error("preview iframe has no content window");
const postMessage = vi.spyOn(frameWindow, "postMessage");
act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
expect(postMessage).not.toHaveBeenCalled();
const editor = document.body.appendChild(document.createElement("textarea"));
act(() => picker().enablePick());
act(() => editor.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true })));
expect(picker().isPickMode).toBe(true);
});
it("survives repeated enable and cancellation cycles", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
for (let cycle = 0; cycle < 3; cycle += 1) {
act(() => picker().enablePick());
expect(picker().isPickMode).toBe(true);
pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
expect(picker().isPickMode).toBe(false);
expect(picker().pickedElement?.selector).toBe("h1");
}
});
it("removes its Studio key listener and disables the runtime on unmount", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
const frameWindow = iframe.contentWindow;
if (!frameWindow) throw new Error("preview iframe has no content window");
const removeEventListener = vi.spyOn(window, "removeEventListener");
const postMessage = vi.spyOn(frameWindow, "postMessage");
act(() => picker().enablePick());
act(() => root?.unmount());
root = null;
expect(removeEventListener.mock.calls.some(([type]) => type === "keydown")).toBe(true);
expect(
postMessage.mock.calls.some(
([message]) =>
typeof message === "object" &&
message !== null &&
"action" in message &&
message.action === "disable-pick-mode",
),
).toBe(true);
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
});
it("commits a normal pick and clears hover state", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
act(() => picker().enablePick());
pickerMessage(iframe.contentWindow, {
type: "element-hovered",
elementInfo: hoverInfo(),
});
picked(iframe.contentWindow, "div.final");
expect(picker().isPickMode).toBe(false);
expect(picker().pickedElement?.selector).toBe("div.final");
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
});
it("clears the label after cancellation", () => {
const { iframe, picker } = mountPicker({ "index.html": SAVED });
act(() => picker().enablePick());
pickerMessage(iframe.contentWindow, {
type: "element-hovered",
elementInfo: hoverInfo({ id: "hero-title", tagName: "h1" }),
});
expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe(
"h1#hero-title",
);
pickerMessage(iframe.contentWindow, { type: "pick-mode-cancelled" });
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
});
});
describe("an edit to a picked element without an id", () => {
it("writes only that edit into the saved file", () => {
const { picker, synced } = mountPicker({ "index.html": SAVED });
@@ -185,8 +351,9 @@ describe("a pick across a reload that swaps the preview frame", () => {
return null;
}
root = createRoot(document.createElement("div"));
act(() => root?.render(React.createElement(Harness)));
return { live, ref, picker: () => api as ReturnType<typeof useElementPicker> };
const rerender = () => act(() => root?.render(React.createElement(Harness)));
rerender();
return { live, ref, rerender, picker: () => api as ReturnType<typeof useElementPicker> };
}
it("keeps a pick posted by the frame it was made in after a new frame took its place", () => {
@@ -212,6 +379,90 @@ describe("a pick across a reload that swaps the preview frame", () => {
expect(picker().pickedElement?.selector).toBe("h1");
});
it("drops hover messages from a primary iframe after it is replaced", () => {
const { live, ref, rerender, picker } = mountSwapping();
const liveWindow = live.contentWindow;
if (!liveWindow) throw new Error("preview iframe has no content window");
const oldPostMessage = vi.spyOn(liveWindow, "postMessage");
act(() => picker().enablePick());
pickerMessage(liveWindow, {
type: "element-hovered",
elementInfo: hoverInfo(),
});
expect(document.querySelector("[data-hf-picker-hover-label]")).not.toBeNull();
const replacement = mountPreview();
const replacementWindow = replacement.contentWindow;
if (!replacementWindow) throw new Error("replacement iframe has no content window");
const replacementPostMessage = vi.spyOn(replacementWindow, "postMessage");
ref.current = replacement;
rerender();
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
expect(
oldPostMessage.mock.calls.some(
([message]) =>
typeof message === "object" &&
message !== null &&
"action" in message &&
message.action === "disable-pick-mode",
),
).toBe(true);
expect(
replacementPostMessage.mock.calls.some(
([message]) =>
typeof message === "object" &&
message !== null &&
"action" in message &&
message.action === "enable-pick-mode",
),
).toBe(true);
pickerMessage(liveWindow, {
type: "element-hovered",
elementInfo: hoverInfo({ id: "stale" }),
});
expect(document.querySelector("[data-hf-picker-hover-label]")).toBeNull();
});
it("moves active pick mode to a zoomed iframe without losing the original selection", () => {
const { live, picker } = mountSwapping();
picked(live.contentWindow, "h1");
const zoom = mountPreview();
const zoomWindow = zoom.contentWindow;
if (!zoomWindow) throw new Error("zoom iframe has no content window");
const zoomPostMessage = vi.spyOn(zoomWindow, "postMessage");
act(() => picker().enablePick());
act(() => picker().setActiveIframe(zoom));
pickerMessage(zoomWindow, {
type: "element-hovered",
elementInfo: hoverInfo({ id: "zoomed" }),
});
pickerMessage(zoomWindow, {
type: "element-pick-candidates",
candidates: [{ selector: "div.zoomed", tagName: "div" }],
selectedIndex: 0,
point: { x: 1, y: 1 },
});
expect(picker().activeIframeRef.current).toBe(zoom);
expect(
zoomPostMessage.mock.calls.some(
([message]) =>
typeof message === "object" &&
message !== null &&
"action" in message &&
message.action === "enable-pick-mode",
),
).toBe(true);
expect(document.querySelector("[data-hf-picker-hover-label]")?.textContent).toBe("div#zoomed");
act(() => picker().setActiveIframe(null));
act(() => window.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape" })));
expect(picker().pickedElement?.selector).toBe("h1");
expect(picker().activeIframeRef.current).toBe(live);
});
it("still ignores a frame it never showed", () => {
const { picker } = mountSwapping();
const stranger = mountPreview();
+237 -48
View File
@@ -1,4 +1,4 @@
import { useState, useCallback, useRef } from "react";
import { useState, useCallback, useEffect, useRef } from "react";
import { useMountEffect } from "./useMountEffect";
import {
resolveSourceFile,
@@ -13,6 +13,11 @@ import {
} from "../player/lib/runtimeProtocol";
import { compositionPathOfPreviewUrl } from "../player/components/CompositionThumbnail";
import { getSourceFileForElement } from "../components/editor/domEditingDom";
import {
createElementPickerHoverLabel,
type ElementPickerHoverInfo,
type ElementPickerHoverLabel,
} from "./elementPickerHoverLabel";
export interface PickedElement {
id: string | null;
@@ -51,54 +56,142 @@ interface PickerOptions {
onSyncFiles?: (files: Record<string, string>) => void;
}
/**
* Hook for element picking via the HyperFrame runtime's picker API.
* Communicates with the iframe via postMessage.
*/
export function useElementPicker(
interface UseElementPickerSessionReturn extends Omit<
UseElementPickerReturn,
"setStyle" | "setDataAttr" | "setTextContent"
> {
setPickedElement: React.Dispatch<React.SetStateAction<PickedElement | null>>;
getActiveIframe: () => HTMLIFrameElement | null;
}
function usePickerHoverLabel(): {
clearHover: () => void;
disposeHover: () => void;
showHover: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void;
} {
const hoverLabelRef = useRef<ElementPickerHoverLabel | null>(null);
const clearHover = useCallback(() => hoverLabelRef.current?.clear(), []);
const disposeHover = useCallback(() => hoverLabelRef.current?.dispose(), []);
const showHover = useCallback((info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => {
hoverLabelRef.current ??= createElementPickerHoverLabel();
hoverLabelRef.current.show(info, iframe);
}, []);
return { clearHover, disposeHover, showHover };
}
function useActivePickerIframe(
iframeRef: React.RefObject<HTMLIFrameElement | null>,
options?: PickerOptions,
): UseElementPickerReturn {
isPickModeRef: React.RefObject<boolean>,
clearHover: () => void,
): {
activeIframeRef: React.RefObject<HTMLIFrameElement | null>;
getActiveIframe: () => HTMLIFrameElement | null;
setActiveIframe: (el: HTMLIFrameElement | null) => void;
} {
const activeOverrideRef = useRef<HTMLIFrameElement | null>(null);
const activeIframeRef = useRef<HTMLIFrameElement | null>(null);
const lastRenderedActiveIframeRef = useRef<HTMLIFrameElement | null>(null);
const getActiveIframe = useCallback(
() => activeOverrideRef.current ?? iframeRef.current,
[iframeRef],
);
const setActiveIframe = useCallback(
(el: HTMLIFrameElement | null) => {
const previous = activeOverrideRef.current ?? iframeRef.current;
const next = el ?? iframeRef.current;
if (previous === next) return;
clearHover();
if (isPickModeRef.current) postPickerControl(previous, "disable-pick-mode");
activeOverrideRef.current = el;
activeIframeRef.current = next;
lastRenderedActiveIframeRef.current = next;
if (isPickModeRef.current) postPickerControl(next, "enable-pick-mode");
},
[clearHover, iframeRef, isPickModeRef],
);
const renderedActiveIframe = getActiveIframe();
useEffect(() => {
const previous = lastRenderedActiveIframeRef.current;
if (previous !== renderedActiveIframe) {
clearHover();
if (isPickModeRef.current) {
postPickerControl(previous, "disable-pick-mode");
postPickerControl(renderedActiveIframe, "enable-pick-mode");
}
}
lastRenderedActiveIframeRef.current = renderedActiveIframe;
}, [clearHover, isPickModeRef, renderedActiveIframe]);
activeIframeRef.current = getActiveIframe();
return { activeIframeRef, getActiveIframe, setActiveIframe };
}
function useElementPickerSession(
iframeRef: React.RefObject<HTMLIFrameElement | null>,
): UseElementPickerSessionReturn {
const [isPickMode, setIsPickMode] = useState(false);
const [pickedElement, setPickedElement] = useState<PickedElement | null>(null);
// Secondary/override iframe ref — set when a zoomed frame is active.
// When set, all postMessage sends and DOM reads go to this ref instead.
const activeOverrideRef = useRef<HTMLIFrameElement | null>(null);
const getActiveIframe = useCallback((): HTMLIFrameElement | null => {
return activeOverrideRef.current ?? iframeRef.current;
}, [iframeRef]);
// Exposed so the host page can wire the focused view's iframe into the picker
const setActiveIframe = useCallback((el: HTMLIFrameElement | null) => {
activeOverrideRef.current = el;
}, []);
const isPickModeRef = useRef(false);
const pickedElementRef = useRef<PickedElement | null>(null);
pickedElementRef.current = pickedElement;
const pickStartSelectionRef = useRef<PickedElement | null | undefined>(undefined);
const { clearHover, disposeHover, showHover } = usePickerHoverLabel();
const { activeIframeRef, getActiveIframe, setActiveIframe } = useActivePickerIframe(
iframeRef,
isPickModeRef,
clearHover,
);
const enablePick = useCallback(() => {
try {
postRuntimeControlMessage(getActiveIframe()?.contentWindow, "enable-pick-mode");
setIsPickMode(true);
} catch {
/* cross-origin */
}
if (isPickModeRef.current || !postPickerControl(getActiveIframe(), "enable-pick-mode")) return;
pickStartSelectionRef.current = pickedElementRef.current;
isPickModeRef.current = true;
setIsPickMode(true);
}, [getActiveIframe]);
const disablePick = useCallback(() => {
try {
postRuntimeControlMessage(getActiveIframe()?.contentWindow, "disable-pick-mode");
} catch {
/* cross-origin */
}
setIsPickMode(false);
}, [getActiveIframe]);
const cancelPick = useCallback(
(notifyRuntime: boolean) => {
if (notifyRuntime) {
postPickerControl(getActiveIframe(), "disable-pick-mode");
}
const selection = pickStartSelectionRef.current;
pickStartSelectionRef.current = undefined;
if (selection !== undefined) {
pickedElementRef.current = selection;
setPickedElement(selection);
}
isPickModeRef.current = false;
clearHover();
setIsPickMode(false);
},
[clearHover, getActiveIframe],
);
const disablePick = useCallback(() => cancelPick(true), [cancelPick]);
const clearPick = useCallback(() => {
pickedElementRef.current = null;
setPickedElement(null);
}, []);
const windowsThatWerePrimary = useRef(new WeakSet<MessageEventSource>());
useEffect(() => {
if (!isPickMode) return;
const handleKeyDown = (event: KeyboardEvent) => {
if (
event.key !== "Escape" ||
event.defaultPrevented ||
event.isComposing ||
elementOwnsEscape(event.target)
)
return;
event.preventDefault();
disablePick();
};
window.addEventListener("keydown", handleKeyDown);
return () => window.removeEventListener("keydown", handleKeyDown);
}, [disablePick, isPickMode]);
// Listen for picker messages from the iframe
useMountEffect(() => {
// One guard per message field, then one branch per message type.
@@ -119,31 +212,81 @@ export function useElementPicker(
)
return;
if (data.type === "element-hovered") {
if (e.source !== activeIframe.contentWindow || !isPickModeRef.current) return;
const info = toHoverInfo(data.elementInfo);
if (info) showHover(info, activeIframe);
return;
}
if (data.type === "element-picked" && data.elementInfo) {
setPickedElement(toPickedElement(data.elementInfo, activeIframe));
const next = toPickedElement(data.elementInfo, activeIframe);
pickedElementRef.current = next;
setPickedElement(next);
pickStartSelectionRef.current = undefined;
isPickModeRef.current = false;
clearHover();
setIsPickMode(false);
} else if (data.type === "element-pick-candidates") {
// Multiple candidates at click point — pick the first one
const el = data.candidates?.[data.selectedIndex ?? 0];
if (el) setPickedElement(toPickedElement(el, activeIframe));
if (el) {
const next = toPickedElement(el, activeIframe);
pickedElementRef.current = next;
setPickedElement(next);
}
}
if (data.type === "pick-mode-cancelled") {
setIsPickMode(false);
cancelPick(false);
}
};
window.addEventListener("message", handleMessage);
return () => window.removeEventListener("message", handleMessage);
return () => {
window.removeEventListener("message", handleMessage);
if (isPickModeRef.current) {
postPickerControl(getActiveIframe(), "disable-pick-mode");
}
disposeHover();
};
});
// Ref for options to avoid stale closures in debounced callback
return {
isPickMode,
pickedElement,
setPickedElement,
getActiveIframe,
enablePick,
disablePick,
clearPick,
setActiveIframe,
activeIframeRef,
};
}
/** Element picking through the HyperFrame runtime's postMessage API. */
export function useElementPicker(
iframeRef: React.RefObject<HTMLIFrameElement | null>,
options?: PickerOptions,
): UseElementPickerReturn {
const {
isPickMode,
pickedElement,
setPickedElement,
getActiveIframe,
enablePick,
disablePick,
clearPick,
setActiveIframe,
activeIframeRef,
} = useElementPickerSession(iframeRef);
const optionsRef = useRef(options);
optionsRef.current = options;
const pendingWritesRef = useRef(new Map<string, PendingWrite>());
settlePendingWrites(pendingWritesRef.current, options?.workspaceFiles);
// Sync immediately (not debounced) — save on every change for reliability
const syncToSource = useCallback(
(picked: PickedElement, live: HTMLElement, iframe: HTMLIFrameElement, op: PatchOperation) => {
const opts = optionsRef.current;
@@ -191,7 +334,7 @@ export function useElementPicker(
/* cross-origin */
}
},
[pickedElement, getActiveIframe, syncToSource],
[pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
const setDataAttr = useCallback(
@@ -221,7 +364,7 @@ export function useElementPicker(
/* cross-origin */
}
},
[pickedElement, getActiveIframe, syncToSource],
[pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
const setTextContent = useCallback(
@@ -244,13 +387,9 @@ export function useElementPicker(
/* cross-origin */
}
},
[pickedElement, getActiveIframe, syncToSource],
[pickedElement, getActiveIframe, setPickedElement, syncToSource],
);
// Ref-like object that always points to the active iframe (override or primary)
const activeIframeRef = useRef<HTMLIFrameElement | null>(null);
activeIframeRef.current = getActiveIframe();
return {
isPickMode,
pickedElement,
@@ -266,6 +405,56 @@ export function useElementPicker(
};
}
function elementOwnsEscape(target: EventTarget | null): boolean {
if (!(target instanceof Element)) return false;
return Boolean(
target.closest(
'dialog,[role="dialog"],[aria-modal="true"],input,textarea,select,[contenteditable="true"],[contenteditable=""],[data-studio-escape-owner]',
),
);
}
function postPickerControl(
iframe: HTMLIFrameElement | null | undefined,
action: "enable-pick-mode" | "disable-pick-mode",
): boolean {
try {
postRuntimeControlMessage(iframe?.contentWindow, action);
return true;
} catch {
return false;
}
}
function isUnknownRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
function isFiniteNumber(value: unknown): value is number {
return typeof value === "number" && Number.isFinite(value);
}
function isOptionalString(value: unknown): value is string | null | undefined {
return value === null || value === undefined || typeof value === "string";
}
function toHoverInfo(value: unknown): ElementPickerHoverInfo | null {
if (!isUnknownRecord(value)) return null;
const info = value;
const box = info.boundingBox;
if (typeof info.tagName !== "string" || !isUnknownRecord(box)) return null;
const coordinates = [box.x, box.y, box.width, box.height];
if (!coordinates.every(isFiniteNumber)) return null;
const [x, y, width, height] = coordinates as [number, number, number, number];
if (!isOptionalString(info.id) || !isOptionalString(info.className)) return null;
return {
id: typeof info.id === "string" ? info.id : null,
className: typeof info.className === "string" ? info.className : null,
tagName: info.tagName,
boundingBox: { x, y, width, height },
};
}
type PickedElementInfo = Partial<Omit<PickedElement, "computedStyles">>;
// workspaceFiles lags this hook's own writes until the host rerenders.