Skip to content

Commit 400925f

Browse files
fix(keyframes): resolve helper-returned DOM targets (#3688)
1 parent 5c44cd2 commit 400925f

4 files changed

Lines changed: 135 additions & 10 deletions

File tree

‎packages/cli/src/commands/keyframes.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -192,6 +192,20 @@ describe("keyframes runtime surfacing", () => {
192192

193193
expect(selectors).toEqual(expect.arrayContaining([".dot", ".chip"]));
194194
});
195+
196+
it("does not forward unresolved static targets as concrete shot selectors", () => {
197+
const html = wrap(`
198+
const tl = gsap.timeline({ paused: true });
199+
tl.to(runtimeOnlyTarget(), { x: 240, duration: 1 });
200+
tl.to("#drag", { x: 240, duration: 1 });
201+
`);
202+
203+
const selectors = collectShotSelectors([
204+
surfaceComposition(html, "helper.html", "helper.html"),
205+
]).map((item) => item.selector);
206+
207+
expect(selectors).toEqual(["#drag"]);
208+
});
195209
});
196210

197211
describe("keyframes template-wrapped sub-compositions", () => {

‎packages/cli/src/commands/keyframes.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -659,7 +659,7 @@ function addTraceSelectors(selectors: Set<string>, cmp: SurfacedComposition): vo
659659

660660
function addTweenSelectors(selectors: Set<string>, cmp: SurfacedComposition): void {
661661
for (const t of cmp.tweens) {
662-
if (t.method !== "set") selectors.add(t.target);
662+
if (t.method !== "set" && t.target !== "__unresolved__") selectors.add(t.target);
663663
}
664664
}
665665

@@ -701,7 +701,7 @@ function onionShotGuardError(
701701
// The rendered onion (--ghost) screenshots the whole painted stage, so it does
702702
// not need an animated DOM element to sample — only the marker onion does.
703703
if (requests.length === 0 && !ghost)
704-
return "--shot: no animated element to sample for the selection.";
704+
return "--shot: no statically resolved animated element to sample for the selection. Use a direct DOM selector or --ghost for runtime-only targets.";
705705
return null;
706706
}
707707

‎packages/parsers/src/gsapParser.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1241,6 +1241,22 @@ describe("variable-target resolution (querySelector pattern)", () => {
12411241
expect(result.animations.map((a) => a.targetSelector)).toEqual([".literal", ".kicker"]);
12421242
});
12431243

1244+
it("resolves a DOM target returned by a lexical helper", () => {
1245+
const script = `
1246+
function scoped(id) {
1247+
return document.getElementById(id);
1248+
}
1249+
const tl = gsap.timeline({ paused: true });
1250+
const target = scoped("drag");
1251+
tl.to(target, { x: 240, duration: 1 }, 0);
1252+
`;
1253+
1254+
const result = parseGsapScript(script);
1255+
1256+
expect(result.animations[0]?.targetSelector).toBe("#drag");
1257+
expect(result.animations[0]?.hasUnresolvedSelector).toBeUndefined();
1258+
});
1259+
12441260
it("parses every tween in a real-world IIFE composition with interleaved gsap.set", () => {
12451261
const result = parseGsapScript(REAL_WORLD_SCRIPT);
12461262
expect(result.animations.map((a) => a.targetSelector)).toEqual([

‎packages/parsers/src/gsapParser.ts‎

Lines changed: 103 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -216,6 +216,13 @@ function scopeChainOf(path: AstPath): AstNode[] {
216216
/** Per-scope element bindings: scopeNode → (variable name → selector). */
217217
type TargetBindings = Map<any, Map<string, string>>;
218218

219+
interface TargetHelper {
220+
params: string[];
221+
returnNode: AstNode;
222+
}
223+
224+
type TargetHelpers = Map<any, Map<string, TargetHelper>>;
225+
219226
function addBinding(
220227
bindings: TargetBindings,
221228
scopeNode: AstNode,
@@ -230,26 +237,110 @@ function addBinding(
230237
if (!scoped.has(name)) scoped.set(name, selector);
231238
}
232239

240+
function directHelperReturn(node: AstNode): AstNode | null {
241+
if (node.type === "ArrowFunctionExpression" && node.body?.type !== "BlockStatement") {
242+
return node.body;
243+
}
244+
if (!isFunctionNode(node) || node.body?.type !== "BlockStatement") return null;
245+
const returns = (node.body.body ?? []).filter(
246+
(statement: AstNode) => statement.type === "ReturnStatement" && statement.argument,
247+
);
248+
return returns.length === 1 ? returns[0].argument : null;
249+
}
250+
251+
function collectTargetHelpers(ast: AstNode): TargetHelpers {
252+
const helpers: TargetHelpers = new Map();
253+
const add = (scopeNode: AstNode, name: string, fn: AstNode): void => {
254+
const returnNode = directHelperReturn(fn);
255+
const params = (fn.params ?? [])
256+
.filter((param: AstNode) => param.type === "Identifier")
257+
.map((param: AstNode) => param.name);
258+
if (!returnNode || params.length !== (fn.params?.length ?? 0)) return;
259+
let scoped = helpers.get(scopeNode);
260+
if (!scoped) {
261+
scoped = new Map();
262+
helpers.set(scopeNode, scoped);
263+
}
264+
if (!scoped.has(name)) scoped.set(name, { params, returnNode });
265+
};
266+
267+
recast.types.visit(ast, {
268+
visitFunctionDeclaration(path: AstPath) {
269+
const name = path.node.id?.name;
270+
const scopeNode = enclosingScopeNode(path);
271+
if (name && scopeNode) add(scopeNode, name, path.node);
272+
this.traverse(path);
273+
},
274+
visitVariableDeclarator(path: AstPath) {
275+
const name = path.node.id?.name;
276+
const fn = path.node.init;
277+
const scopeNode = enclosingScopeNode(path);
278+
if (name && fn && isFunctionNode(fn) && scopeNode) add(scopeNode, name, fn);
279+
this.traverse(path);
280+
},
281+
});
282+
return helpers;
283+
}
284+
285+
function lookupTargetHelper(
286+
name: string,
287+
path: AstPath,
288+
helpers: TargetHelpers,
289+
): TargetHelper | null {
290+
for (const scopeNode of scopeChainOf(path)) {
291+
const helper = helpers.get(scopeNode)?.get(name);
292+
if (helper) return helper;
293+
}
294+
return null;
295+
}
296+
297+
function selectorFromTargetCall(
298+
node: AstNode,
299+
path: AstPath,
300+
scope: ScopeBindings,
301+
helpers: TargetHelpers,
302+
): string | null {
303+
const direct = selectorFromQueryCall(node, scope);
304+
if (direct) return direct;
305+
if (node?.type !== "CallExpression" || node.callee?.type !== "Identifier") return null;
306+
const helper = lookupTargetHelper(node.callee.name, path, helpers);
307+
if (!helper || helper.params.length !== (node.arguments?.length ?? 0)) return null;
308+
309+
const helperScope = new Map(scope);
310+
for (let i = 0; i < helper.params.length; i += 1) {
311+
const param = helper.params[i];
312+
if (!param) return null;
313+
const value = resolveNode(node.arguments[i], scope);
314+
if (value === undefined) return null;
315+
helperScope.set(param, value);
316+
}
317+
return selectorFromQueryCall(helper.returnNode, helperScope);
318+
}
319+
233320
/**
234321
* Build a lexically-scoped index of element variables → selector. Two passes:
235322
* (1) direct DOM-lookup assignments (`const x = root.querySelector(...)`), then
236323
* (2) iteration callback params (`coll.forEach(el => …)`), whose element type is
237324
* the collection's selector — resolved against the pass-1 bindings.
238325
*/
239-
function collectTargetBindings(ast: AstNode, scope: ScopeBindings): TargetBindings {
326+
function collectTargetBindings(
327+
ast: AstNode,
328+
scope: ScopeBindings,
329+
helpers: TargetHelpers,
330+
): TargetBindings {
240331
const bindings: TargetBindings = new Map();
241332

242333
recast.types.visit(ast, {
243334
visitVariableDeclarator(path: AstPath) {
244335
const name = path.node.id?.name;
245-
const selector = selectorFromQueryCall(path.node.init, scope);
336+
const selector = selectorFromTargetCall(path.node.init, path, scope, helpers);
246337
const scopeNode = enclosingScopeNode(path);
247338
if (name && selector !== null && scopeNode) addBinding(bindings, scopeNode, name, selector);
248339
this.traverse(path);
249340
},
250341
visitAssignmentExpression(path: AstPath) {
251342
const left = path.node.left;
252-
const selector = selectorFromQueryCall(path.node.right, scope);
343+
const selector = selectorFromTargetCall(path.node.right, path, scope, helpers);
253344
const scopeNode = enclosingScopeNode(path);
254345
if (left?.type === "Identifier" && selector !== null && scopeNode) {
255346
addBinding(bindings, scopeNode, left.name, selector);
@@ -324,6 +415,7 @@ function resolveTargetSelector(
324415
path: AstPath,
325416
scope: ScopeBindings,
326417
bindings: TargetBindings,
418+
helpers: TargetHelpers,
327419
): string | null {
328420
if (!node) return null;
329421
if (node.type === "StringLiteral" || node.type === "Literal") {
@@ -333,11 +425,11 @@ function resolveTargetSelector(
333425
return lookupBinding(node.name, path, bindings);
334426
}
335427
if (node.type === "CallExpression") {
336-
return selectorFromQueryCall(node, scope);
428+
return selectorFromTargetCall(node, path, scope, helpers);
337429
}
338430
if (node.type === "ArrayExpression") {
339431
const parts = node.elements
340-
.map((el: AstNode) => resolveTargetSelector(el, path, scope, bindings))
432+
.map((el: AstNode) => resolveTargetSelector(el, path, scope, bindings, helpers))
341433
.filter((s: string | null): s is string => typeof s === "string" && s.length > 0);
342434
return parts.length > 0 ? parts.join(", ") : null;
343435
}
@@ -518,6 +610,7 @@ function findAllTweenCalls(
518610
ref: TimelineRef,
519611
scope: ScopeBindings,
520612
targetBindings: TargetBindings,
613+
targetHelpers: TargetHelpers,
521614
): TweenCallInfo[] {
522615
const results: TweenCallInfo[] = [];
523616
recast.types.visit(ast, {
@@ -554,7 +647,8 @@ function findAllTweenCalls(
554647
return;
555648
}
556649
const selectorValue =
557-
resolveTargetSelector(args[0], path, scope, targetBindings) ?? "__unresolved__";
650+
resolveTargetSelector(args[0], path, scope, targetBindings, targetHelpers) ??
651+
"__unresolved__";
558652

559653
if (method === "fromTo") {
560654
results.push({
@@ -1178,11 +1272,12 @@ interface ParsedGsapAst {
11781272
function parseGsapAst(script: string): ParsedGsapAst {
11791273
const ast = parseScript(script);
11801274
const scope = collectScopeBindings(ast);
1181-
const targetBindings = collectTargetBindings(ast, scope);
1275+
const targetHelpers = collectTargetHelpers(ast);
1276+
const targetBindings = collectTargetBindings(ast, scope, targetHelpers);
11821277
const detection = findTimelineVar(ast, scope);
11831278
const ref: TimelineRef = detection.ref ?? { kind: "identifier", name: "tl" };
11841279
const timelineVar = timelineRootSource(ref);
1185-
const calls = findAllTweenCalls(ast, ref, scope, targetBindings);
1280+
const calls = findAllTweenCalls(ast, ref, scope, targetBindings, targetHelpers);
11861281
sortBySourcePosition(calls);
11871282
const rawAnims = calls.map((call) => tweenCallToAnimation(call, scope));
11881283
applyTimelineDefaults(rawAnims, detection.defaults);

0 commit comments

Comments
 (0)