feat(studio): show canvas gesture position, size and rotation (#5594)

* feat(studio): show live canvas gesture measurements

Candidate source; required readout regressions pass. Browser captures and full Studio validation remain in progress.

* test(studio): explain the React test flag typing boundary

* fix(studio): derive gesture readout from pointer drafts
This commit is contained in:
Dante
2026-11-07 00:10:03 +00:00
committed by GitHub
parent 6c0cab814f
commit a4a84deec5
7 changed files with 322 additions and 13 deletions
@@ -0,0 +1,177 @@
// @vitest-environment happy-dom
import React, { act, type ComponentProps } from "react";
import { createRoot, type Root } from "react-dom/client";
import { afterEach, describe, expect, it, vi } from "vitest";
import { DomEditGestureReadout } from "./DomEditGestureReadout";
import { createGestureReadout, updateGestureReadout } from "./domEditGestureReadoutState";
const frames = vi.hoisted(() => ({ update: () => {} }));
vi.mock("./overlayFrameLoop", () => ({
subscribeOverlayFrame: (update: () => void) => {
frames.update = update;
return () => {
frames.update = () => {};
};
},
}));
// React needs its runtime test flag, which the global typings do not declare.
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
let root: Root | undefined;
afterEach(() => {
act(() => root?.unmount());
document.body.replaceChildren();
vi.clearAllMocks();
});
function mount(kind: "drag" | "resize" | "rotate") {
const host = document.createElement("div");
const overlay = document.createElement("div");
const iframe = document.createElement("iframe");
document.body.append(host, overlay, iframe);
const doc = iframe.contentDocument;
if (!doc) throw new Error("Missing preview document");
const composition = doc.createElement("div");
composition.setAttribute("data-composition-id", "scene");
composition.setAttribute("data-width", "1000");
composition.setAttribute("data-height", "800");
const element = doc.createElement("div");
composition.append(element);
doc.body.append(composition);
let x = 70.25;
let y = 40.75;
const width = 100;
const height = 60;
overlay.getBoundingClientRect = () => new DOMRect(20, 30, 500, 400);
iframe.getBoundingClientRect = () => new DOMRect(20, 30, 500, 400);
composition.getBoundingClientRect = () => new DOMRect(0, 0, 1000, 800);
element.getBoundingClientRect = () => new DOMRect(x, y, width, height);
Object.defineProperties(element, {
offsetWidth: { value: width },
offsetHeight: { value: height },
});
const gestureRef: ComponentProps<typeof DomEditGestureReadout>["gestureRef"] = {
current: {
travelled: true,
readout: createGestureReadout(overlay, iframe, {
left: x / 2,
top: y / 2,
width: width / 2,
height: height / 2,
editScaleX: 0.5,
editScaleY: 0.5,
}),
},
};
const update = (text?: string) =>
updateGestureReadout(
gestureRef.current?.readout,
{
left: x / 2,
top: y / 2,
width: width / 2,
height: height / 2,
editScaleX: 0.5,
editScaleY: 0.5,
},
text,
);
update(kind === "resize" ? "100 × 60" : kind === "rotate" ? "0°" : undefined);
root = createRoot(host);
act(() =>
root?.render(
<DomEditGestureReadout
gestureRef={gestureRef}
overlayRef={{ current: overlay }}
iframeRef={{ current: iframe }}
/>,
),
);
const label = host.querySelector<HTMLDivElement>("[data-dom-edit-gesture-readout]");
if (!label) throw new Error("Missing readout");
Object.defineProperties(label, { offsetWidth: { value: 120 }, offsetHeight: { value: 24 } });
const draw = () => frames.update();
const end = () => {
gestureRef.current = null;
draw();
};
return {
measurements: [overlay, iframe, composition, element].map((node) =>
vi.spyOn(node, "getBoundingClientRect"),
),
element,
gestureRef,
update,
doc,
label,
draw,
end,
move: (nextX: number, nextY: number) => {
x = nextX;
y = nextY;
update();
},
};
}
describe("gesture readout", () => {
it("adds no layout reads while drawing and stays hidden on a plain press", () => {
const view = mount("drag");
const measure = vi.spyOn(Element.prototype, "getBoundingClientRect");
if (!view.gestureRef.current) throw new Error("Missing gesture");
view.gestureRef.current.travelled = false;
view.draw();
expect(view.label.style.display).toBe("none");
view.gestureRef.current.travelled = true;
view.move(120, 70);
view.draw();
view.draw();
expect(view.label.textContent).toBe("Canvas X 120 · Y 70");
expect(measure).not.toHaveBeenCalled();
for (const measurement of view.measurements) expect(measurement).not.toHaveBeenCalled();
measure.mockRestore();
for (const measurement of view.measurements) measurement.mockRestore();
});
it("shows rounded composition coordinates during a move, accounting for preview zoom", () => {
const view = mount("drag");
view.draw();
expect(view.label.textContent).toBe("Canvas X 70 · Y 41");
view.move(120.25, 70.75);
view.draw();
expect(view.label.textContent).toBe("Canvas X 120 · Y 71");
expect(view.doc.querySelector("[data-dom-edit-gesture-readout]")).toBeNull();
view.end();
expect(view.label.style.display).toBe("none");
});
it("shows the actual size draft during resize and hides on release", () => {
const view = mount("resize");
view.draw();
expect(view.label.textContent).toBe("100 × 60");
view.update("144 × 87");
view.draw();
expect(view.label.textContent).toBe("144 × 87");
view.end();
expect(view.label.style.display).toBe("none");
});
it("reads the live angle during rotation and hides on cancellation", () => {
const view = mount("rotate");
view.update("32°");
view.draw();
expect(view.label.textContent).toBe("32°");
view.update("-46°");
view.draw();
expect(view.label.textContent).toBe("-46°");
view.end();
expect(view.label.style.display).toBe("none");
});
it("clamps the label inside the visible overlay at either edge", () => {
const view = mount("drag");
view.move(900, -100);
view.draw();
expect(view.label.style.left).toBe("496px");
expect(view.label.style.top).toBe("4px");
view.move(-900, 900);
view.draw();
expect(view.label.style.left).toBe("4px");
expect(view.label.style.top).toBe("396px");
});
});
@@ -0,0 +1,58 @@
import { useRef, type RefObject } from "react";
import { useMountEffect } from "../../hooks/useMountEffect";
import type { GestureState } from "./domEditOverlayGestures";
import { subscribeOverlayFrame } from "./overlayFrameLoop";
type ReadoutGesture = Pick<GestureState, "readout" | "travelled">;
interface DomEditGestureReadoutProps {
gestureRef: RefObject<ReadoutGesture | null>;
overlayRef: RefObject<HTMLDivElement | null>;
iframeRef: RefObject<HTMLIFrameElement | null>;
}
function positionGestureReadout(label: HTMLDivElement, gesture: ReadoutGesture): void {
const readout = gesture.readout;
if (!readout) return;
const bounds = readout.basis.overlayRect;
const rect = readout.rect;
const minX = Math.max(0, -bounds.left) + 4;
const minY = Math.max(0, -bounds.top) + 4;
const maxX = Math.min(bounds.width, readout.viewportWidth - bounds.left) - 4;
const maxY = Math.min(bounds.height, readout.viewportHeight - bounds.top) - 4;
const x = Math.max(minX, Math.min(maxX, rect.left + rect.width + 8));
const y = Math.max(minY, Math.min(maxY, rect.top - 8));
label.style.left = `${x}px`;
label.style.top = `${y}px`;
label.style.maxWidth = `${Math.max(0, maxX - minX)}px`;
// CSS resolves the label's own size without a synchronous layout read after its text changes.
label.style.transform = `translate(max(-100%, ${minX - x}px), max(-100%, ${minY - y}px))`;
}
export function DomEditGestureReadout({ gestureRef }: DomEditGestureReadoutProps) {
const labelRef = useRef<HTMLDivElement | null>(null);
useMountEffect(() =>
subscribeOverlayFrame(() => {
const label = labelRef.current;
if (!label) return;
const gesture = gestureRef.current;
const text = gesture?.travelled && gesture.readout?.text;
if (!gesture || !text) {
label.style.display = "none";
return;
}
if (label.textContent !== text) label.textContent = text;
label.style.display = "block";
positionGestureReadout(label, gesture);
}),
);
return (
<div
ref={labelRef}
aria-hidden="true"
data-dom-edit-gesture-readout="true"
className="pointer-events-none absolute z-50 overflow-hidden rounded bg-studio-surface px-2 py-1 font-mono text-xs whitespace-nowrap text-studio-text shadow-md"
style={{ display: "none" }}
/>
);
}
@@ -40,6 +40,7 @@ import type { ZOrderAction, ZOrderPatch } from "./canvasContextMenuZOrder";
import { getPreviewTargetFromPointer } from "../../utils/studioPreviewHelpers";
import { logSelect } from "../../utils/selectDebug";
import { useOffCanvasIndicators } from "./useOffCanvasIndicators";
import { DomEditGestureReadout } from "./DomEditGestureReadout";
// Re-exports for external consumers — preserving existing import paths.
export {
@@ -542,6 +543,11 @@ export const DomEditOverlay = memo(function DomEditOverlay({
onBoxClick={handleBoxClick}
/>
)}
<DomEditGestureReadout
gestureRef={gestureRef}
overlayRef={overlayRef}
iframeRef={iframeRef}
/>
<ChildRectOutlines rects={compRect.width > 0 ? childRects : []} />
{/* Mounted here rather than with the selection chrome: the chrome does
not render for every selection, and the toolbar belongs to the
@@ -0,0 +1,55 @@
import { computeOverlayRootScale, type OverlayRootScale } from "./domEditOverlayBasis";
import type { OverlayRect } from "./domEditOverlayGeometry";
export interface GestureReadoutState {
basis: OverlayRootScale;
viewportWidth: number;
viewportHeight: number;
text: string;
rect: OverlayRect;
}
export function createGestureReadout(
overlay: HTMLDivElement | null,
iframe: HTMLIFrameElement | null,
rect: OverlayRect,
): GestureReadoutState | undefined {
const basis =
overlay && iframe && computeOverlayRootScale(overlay, iframe, iframe.contentDocument);
if (!basis || basis.rootScaleX <= 0 || basis.rootScaleY <= 0) return undefined;
return {
basis,
viewportWidth: window.innerWidth,
viewportHeight: window.innerHeight,
text: "",
rect,
};
}
export function updateGestureReadout(
readout: GestureReadoutState | undefined,
rect: OverlayRect,
text?: string,
): void {
if (!readout) return;
const { basis } = readout;
const x = (rect.left - (basis.iframeRect.left - basis.overlayRect.left)) / basis.rootScaleX;
const y = (rect.top - (basis.iframeRect.top - basis.overlayRect.top)) / basis.rootScaleY;
readout.text = text ?? `Canvas X ${Math.round(x)} · Y ${Math.round(y)}`;
readout.rect = rect;
}
export function updateGestureReadoutAngle(
readout: GestureReadoutState | undefined,
angle: number,
): void {
if (readout) updateGestureReadout(readout, readout.rect, `${Math.round(angle)}°`);
}
export function updateGestureReadoutSize(
readout: GestureReadoutState | undefined,
rect: OverlayRect,
size: { width: number; height: number },
): void {
updateGestureReadout(readout, rect, `${Math.round(size.width)} × ${Math.round(size.height)}`);
}
@@ -1,3 +1,4 @@
import type { GestureReadoutState } from "./domEditGestureReadoutState";
import type { RefObject } from "react";
import type { DomEditSelection } from "./domEditing";
import type {
@@ -47,6 +48,7 @@ const ROTATION_SNAP_DEGREES = 15;
export const ROTATED_SNAP_BYPASS_DEGREES = 0.5;
export interface GestureState {
readout?: GestureReadoutState;
kind: GestureKind;
mode: "path-offset" | "box-size" | "rotation";
selection: DomEditSelection;
@@ -311,3 +313,13 @@ export type UseDomEditOverlayGesturesOptions = {
onCanvasMouseDown: (e: React.MouseEvent<HTMLDivElement>, o?: PreviewMouseDownOptions) => void;
snapGuidesRef: RefObject<SnapGuidesState | null>;
};
export function isDomEditGestureTap(
g: { startX: number; startY: number; travelled?: boolean },
e: React.PointerEvent,
) {
return (
!g.travelled &&
Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
);
}
@@ -1,3 +1,4 @@
import { createGestureReadout } from "./domEditGestureReadoutState";
/**
* Gesture-begin functions: startGroupDrag and startGesture.
* These are pure "start a new gesture" operations — no draft rect updates.
@@ -278,6 +279,7 @@ export function startGesture(
opts.rafPausedRef.current = true;
opts.gestureRef.current = {
kind,
readout: createGestureReadout(overlayEl, iframe, rect),
mode,
selection: sel,
pointerId: e.pointerId,
@@ -1,3 +1,4 @@
import * as readout from "./domEditGestureReadoutState";
import { createPreviewGestureStarts } from "./previewGestureStarts";
import { trackPreviewEditResult } from "../../utils/previewFeatureUsage";
// fallow-ignore-file code-duplication
@@ -40,6 +41,7 @@ import {
hasDomEditRotationChanged,
lockDragToDominantAxis,
movesGesture,
isDomEditGestureTap,
resolveDomEditRotationGesture,
} from "./domEditOverlayGestures";
import { resolveCenterResizeSize } from "./domEditResizeLocal";
@@ -58,13 +60,6 @@ import { createGroupDragMover } from "./groupDragMove";
import { DomEditSaveQueueOpenError } from "../../utils/domEditSaveQueue";
import { beginStudioPendingEdit } from "../../utils/studioPendingEdits";
function isTap(g: { startX: number; startY: number; travelled?: boolean }, e: React.PointerEvent) {
return (
!g.travelled &&
Math.hypot(e.clientX - g.startX, e.clientY - g.startY) < BLOCKED_MOVE_THRESHOLD_PX
);
}
function logGestureCommitFailure(message: string, error: unknown): void {
if (error instanceof DomEditSaveQueueOpenError) return;
console.error(message, error);
@@ -147,13 +142,13 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
}
if (groupG) {
if (!isTap(groupG, e)) groupG.travelled = true;
if (!isDomEditGestureTap(groupG, e)) groupG.travelled = true;
moveGroupDrag(groupG, e);
return;
}
if (!g || !sel) return;
if (!isTap(g, e)) g.travelled = true;
if (!isDomEditGestureTap(g, e)) g.travelled = true;
let dx = e.clientX - g.startX;
let dy = e.clientY - g.startY;
@@ -170,6 +165,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
actualAngle: g.actualRotation,
snap: e.shiftKey,
});
readout.updateGestureReadoutAngle(g.readout, rotated.angle);
applyRotationDraft(sel.element, rotated.angle, g.plainRotation);
return;
}
@@ -234,7 +230,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
const nextBoxLeft = g.originLeft + dx;
const nextBoxTop = g.originTop + dy;
setDraftOverlayRect({
const draftRect = {
left: nextBoxLeft,
top: nextBoxTop,
width: g.originWidth,
@@ -242,7 +238,9 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
editScaleX: g.editScaleX,
editScaleY: g.editScaleY,
angle: g.actualRotation,
});
};
readout.updateGestureReadout(g.readout, draftRect);
setDraftOverlayRect(draftRect);
if (box) {
box.style.left = `${nextBoxLeft}px`;
box.style.top = `${nextBoxTop}px`;
@@ -286,6 +284,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
box.style.width = `${draftRect.width}px`;
box.style.height = `${draftRect.height}px`;
}
readout.updateGestureReadoutSize(g.readout, draftRect, writtenSize);
setDraftOverlayRect(draftRect);
}
};
@@ -316,7 +315,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
const rawDy = e.clientY - groupG.startY;
// Consume the release click so it cannot deselect the moved group.
opts.suppressNextBoxClickRef.current = true;
if (isTap(groupG, e)) {
if (isDomEditGestureTap(groupG, e)) {
restoreGroupPathOffsets(groupG);
if (e.shiftKey) {
opts.onCanvasMouseDown(e as unknown as React.MouseEvent<HTMLDivElement>, {
@@ -378,7 +377,7 @@ export function createDomEditOverlayGestureHandlers(opts: UseDomEditOverlayGestu
if (!g || !sel) return;
const movedDistance = Math.hypot(e.clientX - g.startX, e.clientY - g.startY);
if (g.kind === "drag" && isTap(g, e)) {
if (g.kind === "drag" && isDomEditGestureTap(g, e)) {
if (g.pathOffsetMember) restoreManualOffsetDragMembers([g.pathOffsetMember]);
if (box) {
box.style.left = `${g.originLeft}px`;