Skip to content

Commit 4aa6b16

Browse files
feat(studio): a host app can reuse Studio's snapping and marquee selection in its own preview (#4635)
* feat(studio): export snapping, the marquee and picker describe for a host's own preview * fix(studio): a host pick type must bring its own marquee resolver
1 parent 3a64ea8 commit 4aa6b16

9 files changed

Lines changed: 388 additions & 53 deletions

File tree

‎packages/core/src/inline-scripts/pickerApi.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ export type HyperframePickerApi = {
3737
clientY: number,
3838
indexes?: number[],
3939
) => HyperframePickerElementInfo[];
40+
describe?: (element: Element) => HyperframePickerElementInfo | null;
4041
};
4142

4243
declare global {

‎packages/core/src/runtime/picker.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -125,6 +125,7 @@ describe("createPickerModule", () => {
125125
expect(typeof api.getCandidatesAtPoint).toBe("function");
126126
expect(typeof api.pickAtPoint).toBe("function");
127127
expect(typeof api.pickManyAtPoint).toBe("function");
128+
expect(typeof api.describe).toBe("function");
128129
});
129130

130131
it("isActive returns pick mode state", () => {
@@ -305,6 +306,22 @@ describe("createPickerModule", () => {
305306
]);
306307
});
307308

309+
it("describe returns what a click on the same element returns", () => {
310+
const picker = createPickerModule({ postMessage: createMockPostMessage() });
311+
picker.installPickerApi();
312+
document.body.innerHTML = `<div id="root" data-composition-id="main"><p>a</p>
313+
<p class="card" data-start="1">b</p></div>`;
314+
const card = document.querySelector(".card")!;
315+
const api = (window as any).__HF_PICKER_API;
316+
const restore = emulateHitTest(() => [card, document.getElementById("root")!]);
317+
try {
318+
expect(api.describe(card)).toEqual(api.getCandidatesAtPoint(10, 10)[0]);
319+
} finally {
320+
restore();
321+
}
322+
expect(api.describe(document.createTextNode("x"))).toBeNull();
323+
});
324+
308325
it("a section background click picks the host, and an inner root never gets a bare tag selector", () => {
309326
const picker = createPickerModule({ postMessage: createMockPostMessage() });
310327
picker.installPickerApi();

‎packages/core/src/runtime/picker.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,7 @@ export function createPickerModule(deps: PickerModuleDeps): PickerModule {
372372
disablePickMode();
373373
return selected;
374374
},
375+
describe: (element) => (isElementNode(element) ? extractElementInfo(element) : null),
375376
pickManyAtPoint: (clientX, clientY, indexes) => {
376377
if (!Number.isFinite(clientX) || !Number.isFinite(clientY)) return [];
377378
const infos = getPickInfosFromPoint(clientX, clientY, 8);

‎packages/studio/src/components/editor/DomEditOverlay.tsx‎

Lines changed: 2 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -378,9 +378,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
378378
)
379379
: null;
380380
if (freshTarget) return;
381-
const overlayEl = overlayRef.current;
382-
if (overlayEl) {
383-
const oRect = overlayEl.getBoundingClientRect();
381+
if (overlayRef.current) {
384382
// Anywhere empty on the overlay starts one, not just inside the frame.
385383
// An element dragged past the edge sits OUT there in the grey, and a
386384
// rubber band that refuses to start there cannot reach it — which left
@@ -390,17 +388,7 @@ export const DomEditOverlay = memo(function DomEditOverlay({
390388
event.preventDefault();
391389
event.stopPropagation();
392390
suppressNextOverlayMouseDownRef.current = true;
393-
(event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
394-
const cx = event.clientX - oRect.left;
395-
const cy = event.clientY - oRect.top;
396-
marquee.marqueeRef.current = {
397-
startX: cx,
398-
startY: cy,
399-
currentX: cx,
400-
currentY: cy,
401-
pointerId: event.pointerId,
402-
pastThreshold: false,
403-
};
391+
marquee.begin(event);
404392
return;
405393
}
406394
}

‎packages/studio/src/components/editor/MarqueeOverlay.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
import type { Rect } from "../../utils/marqueeGeometry";
22

3-
interface MarqueeOverlayProps {
3+
export interface MarqueeOverlayProps {
44
/** Elements the marquee currently intersects — outlined live before mouse-up. */
55
candidateRects: Rect[];
66
/** The marquee drag rectangle itself, or null when not marquee-selecting. */

‎packages/studio/src/components/editor/SnapGuideOverlay.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ const GUIDE_COLOR = "rgba(255, 68, 204, 0.85)";
1515
const SPACING_COLOR = "rgba(255, 68, 204, 0.6)";
1616
const SPACING_BG = "rgba(255, 68, 204, 0.15)";
1717

18-
interface SnapGuideOverlayProps {
18+
export interface SnapGuideOverlayProps {
1919
snapGuidesRef: RefObject<SnapGuidesState | null>;
2020
/** Composition rect in overlay space — guide lines span exactly this rect. */
2121
compositionLeft: number;

‎packages/studio/src/components/editor/marqueeCommit.ts‎

Lines changed: 100 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ interface MarqueeState {
1414
currentY: number;
1515
pointerId: number;
1616
pastThreshold: boolean;
17+
target: Element;
1718
}
1819

1920
const MARQUEE_THRESHOLD_PX = 4;
@@ -80,14 +81,13 @@ function hitsWithin(rect: Rect, candidates: MarqueeHit[]): MarqueeHit[] {
8081
return candidates.filter((candidate) => rectsOverlap(rect, candidate.rect));
8182
}
8283

83-
async function runMarqueeIntersection(
84-
rect: Rect,
85-
candidates: MarqueeHit[],
84+
async function resolveDomEditSelections(
85+
elements: HTMLElement[],
8686
activeCompositionPath: string,
8787
): Promise<DomEditSelection[]> {
8888
const isMasterView = !activeCompositionPath || activeCompositionPath === "index.html";
8989
const hits: DomEditSelection[] = [];
90-
for (const { element } of hitsWithin(rect, candidates)) {
90+
for (const element of elements) {
9191
const sel = await resolveDomEditSelection(element, {
9292
activeCompositionPath,
9393
isMasterView,
@@ -98,23 +98,48 @@ async function runMarqueeIntersection(
9898
return hits;
9999
}
100100

101-
interface MarqueeGesturesDeps {
101+
export interface MarqueeGesturesDeps<T = DomEditSelection> {
102102
iframeRef: React.RefObject<HTMLIFrameElement | null>;
103103
overlayRef: React.RefObject<HTMLDivElement | null>;
104104
activeCompositionPathRef: React.RefObject<string | null>;
105-
onMarqueeSelectRef: React.RefObject<
106-
((selections: DomEditSelection[], additive: boolean) => void) | undefined
107-
>;
108-
selectionRef: React.RefObject<DomEditSelection | null>;
109-
gestures: {
105+
onMarqueeSelectRef: React.RefObject<((selections: T[], additive: boolean) => void) | undefined>;
106+
/** Turns the elements a drag touched into picks; without it, Studio's edit selections. */
107+
resolveHits?: (elements: HTMLElement[]) => T[] | Promise<T[]>;
108+
selectionRef?: React.RefObject<DomEditSelection | null>;
109+
/** Studio's pointer handling, for the events that are not part of a marquee. */
110+
gestures?: {
110111
onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
111112
onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
112113
clearPointerState: (ref: React.RefObject<DomEditSelection | null>) => void;
113114
};
114115
}
115116

117+
export interface MarqueeGestures {
118+
marqueeRect: Rect | null;
119+
candidateRects: Rect[];
120+
/** Starts a marquee at this press; the host has decided it landed on empty canvas. */
121+
begin: (event: React.PointerEvent<HTMLElement>) => void;
122+
/** Drops an active marquee without selecting anything. */
123+
cancel: () => void;
124+
onPointerMove: (event: React.PointerEvent<HTMLDivElement>) => void;
125+
onPointerUp: (event: React.PointerEvent<HTMLDivElement>) => void;
126+
onPointerCancel: () => void;
127+
}
128+
129+
function releaseCapture(m: MarqueeState): void {
130+
try {
131+
m.target.releasePointerCapture(m.pointerId);
132+
} catch {
133+
/* already released */
134+
}
135+
}
136+
137+
export function useMarqueeGestures(deps: MarqueeGesturesDeps): MarqueeGestures;
138+
export function useMarqueeGestures<T>(
139+
deps: MarqueeGesturesDeps<T> & Required<Pick<MarqueeGesturesDeps<T>, "resolveHits">>,
140+
): MarqueeGestures;
116141
// fallow-ignore-next-line complexity
117-
export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
142+
export function useMarqueeGestures<T>(deps: MarqueeGesturesDeps<T>): MarqueeGestures {
118143
const marqueeRef = useRef<MarqueeState | null>(null);
119144
const [marqueeRect, setMarqueeRect] = useState<Rect | null>(null);
120145
// Live "candidate" highlight: the elements the marquee currently touches,
@@ -135,12 +160,55 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
135160
if (!iframe || !overlay || !deps.onMarqueeSelectRef.current) return;
136161
const acp = deps.activeCompositionPathRef.current ?? "index.html";
137162
const candidates = candidatesRef.current ?? collectMarqueeCandidates(iframe, overlay, acp);
138-
const hits = await runMarqueeIntersection(rect, candidates, acp);
139-
deps.onMarqueeSelectRef.current(hits, additive);
163+
const elements = hitsWithin(rect, candidates).map((hit) => hit.element);
164+
const resolveHits = deps.resolveHits;
165+
const picks = resolveHits
166+
? await resolveHits(elements)
167+
: ((await resolveDomEditSelections(elements, acp)) as T[]);
168+
deps.onMarqueeSelectRef.current?.(picks, additive);
140169
},
141-
[deps.iframeRef, deps.overlayRef, deps.onMarqueeSelectRef, deps.activeCompositionPathRef],
170+
[
171+
deps.iframeRef,
172+
deps.overlayRef,
173+
deps.onMarqueeSelectRef,
174+
deps.activeCompositionPathRef,
175+
deps.resolveHits,
176+
],
142177
);
143178

179+
const reset = useCallback(() => {
180+
marqueeRef.current = null;
181+
setMarqueeRect(null);
182+
setCandidateRects([]);
183+
candidatesRef.current = null;
184+
}, []);
185+
186+
const begin = useCallback(
187+
(event: React.PointerEvent<HTMLElement>) => {
188+
const oRect = deps.overlayRef.current?.getBoundingClientRect();
189+
if (!oRect) return;
190+
event.currentTarget.setPointerCapture(event.pointerId);
191+
const x = event.clientX - oRect.left;
192+
const y = event.clientY - oRect.top;
193+
marqueeRef.current = {
194+
startX: x,
195+
startY: y,
196+
currentX: x,
197+
currentY: y,
198+
pointerId: event.pointerId,
199+
pastThreshold: false,
200+
target: event.currentTarget,
201+
};
202+
},
203+
[deps.overlayRef],
204+
);
205+
206+
const cancel = useCallback(() => {
207+
if (!marqueeRef.current) return;
208+
releaseCapture(marqueeRef.current);
209+
reset();
210+
}, [reset]);
211+
144212
const onPointerMove = useCallback(
145213
(event: React.PointerEvent<HTMLDivElement>) => {
146214
const m = marqueeRef.current;
@@ -172,7 +240,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
172240
}
173241
return;
174242
}
175-
deps.gestures.onPointerMove(event);
243+
deps.gestures?.onPointerMove(event);
176244
},
177245
[deps.gestures, deps.overlayRef, deps.iframeRef, deps.activeCompositionPathRef],
178246
);
@@ -181,12 +249,7 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
181249
(event: React.PointerEvent<HTMLDivElement>) => {
182250
const m = marqueeRef.current;
183251
if (m) {
184-
marqueeRef.current = null;
185-
try {
186-
(event.currentTarget as HTMLElement).releasePointerCapture(m.pointerId);
187-
} catch {
188-
/* already released */
189-
}
252+
releaseCapture(m);
190253
if (m.pastThreshold) {
191254
commitMarquee(
192255
{
@@ -200,26 +263,26 @@ export function useMarqueeGestures(deps: MarqueeGesturesDeps) {
200263
} else {
201264
deps.onMarqueeSelectRef.current?.([], false);
202265
}
203-
setMarqueeRect(null);
204-
setCandidateRects([]);
205-
candidatesRef.current = null;
266+
reset();
206267
return;
207268
}
208-
deps.gestures.onPointerUp(event);
269+
deps.gestures?.onPointerUp(event);
209270
},
210-
[deps.gestures, commitMarquee, deps.onMarqueeSelectRef],
271+
[deps.gestures, commitMarquee, deps.onMarqueeSelectRef, reset],
211272
);
212273

213274
const onPointerCancel = useCallback(() => {
214-
if (marqueeRef.current) {
215-
marqueeRef.current = null;
216-
setMarqueeRect(null);
217-
setCandidateRects([]);
218-
candidatesRef.current = null;
219-
return;
220-
}
221-
deps.gestures.clearPointerState(deps.selectionRef);
222-
}, [deps.gestures, deps.selectionRef]);
223-
224-
return { marqueeRef, marqueeRect, candidateRects, onPointerMove, onPointerUp, onPointerCancel };
275+
if (marqueeRef.current) return cancel();
276+
if (deps.selectionRef) deps.gestures?.clearPointerState(deps.selectionRef);
277+
}, [deps.gestures, deps.selectionRef, cancel]);
278+
279+
return {
280+
marqueeRect,
281+
candidateRects,
282+
begin,
283+
cancel,
284+
onPointerMove,
285+
onPointerUp,
286+
onPointerCancel,
287+
};
225288
}

0 commit comments

Comments
 (0)