diff --git a/docs/packages/studio.mdx b/docs/packages/studio.mdx index 3a93ae113f..77ba6b2ac2 100644 --- a/docs/packages/studio.mdx +++ b/docs/packages/studio.mdx @@ -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. diff --git a/packages/core/src/inline-scripts/pickerApi.ts b/packages/core/src/inline-scripts/pickerApi.ts index fbe0dc72bf..083bbe1f10 100644 --- a/packages/core/src/inline-scripts/pickerApi.ts +++ b/packages/core/src/inline-scripts/pickerApi.ts @@ -7,6 +7,7 @@ export type HyperframePickerBoundingBox = { export type HyperframePickerElementInfo = { id: string | null; + className?: string | null; tagName: string; selector: string; label: string; diff --git a/packages/core/src/runtime/picker.test.ts b/packages/core/src/runtime/picker.test.ts index b354508b3a..cf27cbecb0 100644 --- a/packages/core/src/runtime/picker.test.ts +++ b/packages/core/src/runtime/picker.test.ts @@ -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 = `

Hi

`; + 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", () => { diff --git a/packages/core/src/runtime/picker.ts b/packages/core/src/runtime/picker.ts index 2d2d942e87..584eb421b5 100644 --- a/packages/core/src/runtime/picker.ts +++ b/packages/core/src/runtime/picker.ts @@ -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() }); } diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts b/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts new file mode 100644 index 0000000000..0516480510 --- /dev/null +++ b/packages/studio/src/hooks/elementPickerHoverLabel.browser.test.ts @@ -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> | 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(``); + await page.addScriptTag({ content: bundle.outputFiles[0]?.text }); + + const result = await page.evaluate(() => { + const preview = document.querySelector("#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("[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, + }); +}); diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.test.ts b/packages/studio/src/hooks/elementPickerHoverLabel.test.ts new file mode 100644 index 0000000000..aa3a2d93a3 --- /dev/null +++ b/packages/studio/src/hooks/elementPickerHoverLabel.test.ts @@ -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: `${"x".repeat(100)}`, + className: null, + boundingBox: box, + }); + expect(Array.from(identifier)).toHaveLength(72); + expect(identifier).toMatch(/^div#/); + 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: "not markup", + className: null, + boundingBox: { x: 10, y: 20, width: 30, height: 40 }, + }, + iframe, + ); + + const label = document.querySelector("[data-hf-picker-hover-label]"); + expect(label?.textContent).toBe("div#not markup"); + 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(); + }); +}); diff --git a/packages/studio/src/hooks/elementPickerHoverLabel.ts b/packages/studio/src/hooks/elementPickerHoverLabel.ts new file mode 100644 index 0000000000..a755478c79 --- /dev/null +++ b/packages/studio/src/hooks/elementPickerHoverLabel.ts @@ -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; + 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, + }; +} diff --git a/packages/studio/src/hooks/useElementPicker.test.ts b/packages/studio/src/hooks/useElementPicker.test.ts index 98ae87dda7..8ccc2a4da5 100644 --- a/packages/studio/src/hooks/useElementPicker.test.ts +++ b/packages/studio/src/hooks/useElementPicker.test.ts @@ -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) => + act(() => { + window.dispatchEvent( + new MessageEvent("message", { + source: from, + data: { + source: "hf-preview", + ...data, + ...runtimeProtocolMetadata(30), + }, + }), + ); + }); + +const hoverInfo = (overrides: Record = {}) => ({ + 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; return { + iframe, picker, synced, setHostFiles: (next: Record) => 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 }; + const rerender = () => act(() => root?.render(React.createElement(Harness))); + rerender(); + return { live, ref, rerender, picker: () => api as ReturnType }; } 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(); diff --git a/packages/studio/src/hooks/useElementPicker.ts b/packages/studio/src/hooks/useElementPicker.ts index f4ccfaa557..ef55823dee 100644 --- a/packages/studio/src/hooks/useElementPicker.ts +++ b/packages/studio/src/hooks/useElementPicker.ts @@ -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) => 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>; + getActiveIframe: () => HTMLIFrameElement | null; +} + +function usePickerHoverLabel(): { + clearHover: () => void; + disposeHover: () => void; + showHover: (info: ElementPickerHoverInfo, iframe: HTMLIFrameElement) => void; +} { + const hoverLabelRef = useRef(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, - options?: PickerOptions, -): UseElementPickerReturn { + isPickModeRef: React.RefObject, + clearHover: () => void, +): { + activeIframeRef: React.RefObject; + getActiveIframe: () => HTMLIFrameElement | null; + setActiveIframe: (el: HTMLIFrameElement | null) => void; +} { + const activeOverrideRef = useRef(null); + const activeIframeRef = useRef(null); + const lastRenderedActiveIframeRef = useRef(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, +): UseElementPickerSessionReturn { const [isPickMode, setIsPickMode] = useState(false); const [pickedElement, setPickedElement] = useState(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(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(null); + pickedElementRef.current = pickedElement; + const pickStartSelectionRef = useRef(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()); + 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, + 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()); 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(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 { + 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>; // workspaceFiles lags this hook's own writes until the host rerenders.