Skip to content

Commit 4958a9f

Browse files
fix(lint): warn on undefined GSAP color variables (#3723)
1 parent 00c91d6 commit 4958a9f

3 files changed

Lines changed: 165 additions & 1 deletion

File tree

‎packages/lint/src/rules/composition.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ function collectDeclaredVariableIds(htmlTagRaw: string): Set<string> | null {
224224
* template/fragment sub-comps hold it on their composition root div. Returns
225225
* null if any occurrence has unparseable JSON.
226226
*/
227-
function collectAllDeclaredVariableIds(tags: readonly OpenTag[]): Set<string> | null {
227+
export function collectAllDeclaredVariableIds(tags: readonly OpenTag[]): Set<string> | null {
228228
const all = new Set<string>();
229229
for (const tag of tags) {
230230
if (!readAttr(tag.raw, "data-composition-variables")) continue;

‎packages/lint/src/rules/gsap.test.ts‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,100 @@ import { describe, it, expect } from "vitest";
33
import { lintHyperframeHtml } from "../hyperframeLinter.js";
44

55
describe("GSAP rules", () => {
6+
it("warns when a GSAP color tween uses an undefined CSS variable", async () => {
7+
const html = `
8+
<html><body>
9+
<div data-composition-id="c1" data-width="1920" data-height="1080">
10+
<h1 id="title">Visible text</h1>
11+
</div>
12+
<script>
13+
const tl = gsap.timeline({ paused: true });
14+
tl.to("#title", { color: "var(--accent2)", duration: 0.5 }, 0);
15+
window.__timelines = { c1: tl };
16+
</script>
17+
</body></html>`;
18+
19+
const result = await lintHyperframeHtml(html);
20+
expect(
21+
result.findings.find((finding) => finding.code === "gsap_undefined_css_variable"),
22+
).toMatchObject({
23+
severity: "warning",
24+
selector: "#title",
25+
});
26+
});
27+
28+
it("checks both ends of a fromTo color tween", async () => {
29+
const html = `
30+
<html><body>
31+
<div data-composition-id="c1" data-width="1920" data-height="1080"><h1 id="title">Text</h1></div>
32+
<script>
33+
const tl = gsap.timeline({ paused: true });
34+
tl.fromTo("#title", { color: "var(--missing-from)" }, { color: "#fff", duration: 0.5 }, 0);
35+
window.__timelines = { c1: tl };
36+
</script>
37+
</body></html>`;
38+
39+
const result = await lintHyperframeHtml(html);
40+
expect(
41+
result.findings.find((finding) => finding.code === "gsap_undefined_css_variable")?.message,
42+
).toContain("--missing-from");
43+
});
44+
45+
it.each([
46+
["style block", `<style>:root { --accent2: #ff3366; }</style>`],
47+
["inline style", `<div style="--accent2: #ff3366"></div>`],
48+
])("accepts a GSAP CSS variable defined in a %s", async (_source, definition) => {
49+
const html = `
50+
<html><head>${definition}</head><body>
51+
<div data-composition-id="c1" data-width="1920" data-height="1080"><h1 id="title">Text</h1></div>
52+
<script>
53+
const tl = gsap.timeline({ paused: true });
54+
tl.to("#title", { color: "var(--accent2)", duration: 0.5 }, 0);
55+
window.__timelines = { c1: tl };
56+
</script>
57+
</body></html>`;
58+
59+
const result = await lintHyperframeHtml(html);
60+
expect(
61+
result.findings.find((finding) => finding.code === "gsap_undefined_css_variable"),
62+
).toBeUndefined();
63+
});
64+
65+
it("accepts an undefined CSS variable with a var() fallback", async () => {
66+
const html = `
67+
<html><body>
68+
<div data-composition-id="c1" data-width="1920" data-height="1080"><h1 id="title">Text</h1></div>
69+
<script>
70+
const tl = gsap.timeline({ paused: true });
71+
tl.to("#title", { color: "var(--accent2, #fff)", duration: 0.5 }, 0);
72+
window.__timelines = { c1: tl };
73+
</script>
74+
</body></html>`;
75+
76+
const result = await lintHyperframeHtml(html);
77+
expect(
78+
result.findings.find((finding) => finding.code === "gsap_undefined_css_variable"),
79+
).toBeUndefined();
80+
});
81+
82+
it("accepts a CSS variable declared through data-composition-variables", async () => {
83+
const html = `
84+
<html data-composition-variables='[{"id":"accent2","type":"color","label":"Accent","default":"#ff3366"}]'>
85+
<body>
86+
<div data-composition-id="c1" data-width="1920" data-height="1080"><h1 id="title">Text</h1></div>
87+
<script>
88+
const tl = gsap.timeline({ paused: true });
89+
tl.to("#title", { color: "var(--accent2)", duration: 0.5 }, 0);
90+
window.__timelines = { c1: tl };
91+
</script>
92+
</body></html>`;
93+
94+
const result = await lintHyperframeHtml(html);
95+
expect(
96+
result.findings.find((finding) => finding.code === "gsap_undefined_css_variable"),
97+
).toBeUndefined();
98+
});
99+
6100
it("errors when window.__timelines is registered BEFORE the fonts.ready build", async () => {
7101
const html = `
8102
<html><body>

‎packages/lint/src/rules/gsap.ts‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ import {
4343
WINDOW_TIMELINE_ASSIGN_PATTERN,
4444
TIMELINE_REGISTRY_OBJECT_LITERAL_PATTERN,
4545
} from "../utils";
46+
import { collectAllDeclaredVariableIds } from "./composition";
4647

4748
// ── GSAP-specific types ────────────────────────────────────────────────────
4849

@@ -195,6 +196,44 @@ function zeroValue(value: string | number | undefined): boolean {
195196
return Number(value.trim()) === 0;
196197
}
197198

199+
function isGsapColorProperty(property: string): boolean {
200+
const normalized = property.toLowerCase();
201+
return (
202+
!normalized.startsWith("--") &&
203+
(normalized.endsWith("color") || normalized === "fill" || normalized === "stroke")
204+
);
205+
}
206+
207+
function collectStaticCssVariableDefinitions(
208+
tags: readonly OpenTag[],
209+
styles: LintContext["styles"],
210+
): Set<string> {
211+
const definitions = new Set<string>();
212+
const sources = [
213+
...styles.map((style) => style.content),
214+
...tags.map((tag) => readDecodedAttr(tag.raw, "style") ?? ""),
215+
];
216+
const definitionPattern = /(?:^|[;{])\s*(--[A-Za-z0-9_-]+)\s*:/gm;
217+
for (const source of sources) {
218+
const withoutComments = source.replace(/\/\*[\s\S]*?\*\//g, " ");
219+
for (const match of withoutComments.matchAll(definitionPattern)) {
220+
if (match[1]) definitions.add(match[1]);
221+
}
222+
}
223+
for (const id of collectAllDeclaredVariableIds(tags) ?? []) definitions.add(`--${id}`);
224+
return definitions;
225+
}
226+
227+
function cssVariableReferencesWithoutFallback(value: unknown): string[] {
228+
const text = unwrapRaw(value);
229+
if (typeof text !== "string") return [];
230+
const variables: string[] = [];
231+
for (const match of text.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)\s*(,)?/g)) {
232+
if (match[1] && !match[2]) variables.push(match[1]);
233+
}
234+
return variables;
235+
}
236+
198237
function isHiddenGsapState(values: Record<string, string | number>): boolean {
199238
const visibility = stringValue(values.visibility)?.toLowerCase();
200239
const display = stringValue(values.display)?.toLowerCase();
@@ -1056,6 +1095,37 @@ function collectCssOpacityZeroSelectors(
10561095

10571096
// fallow-ignore-next-line complexity
10581097
export const gsapRules: LintRule<LintContext>[] = [
1098+
// gsap_undefined_css_variable
1099+
async ({ tags, styles, scripts }) => {
1100+
const definedVariables = collectStaticCssVariableDefinitions(tags, styles);
1101+
const findings: HyperframeLintFinding[] = [];
1102+
const reported = new Set<string>();
1103+
for (const script of scripts) {
1104+
for (const win of await cachedExtractGsapWindows(script.content)) {
1105+
for (const values of [win.fromPropertyValues, win.propertyValues]) {
1106+
for (const [property, value] of Object.entries(values ?? {})) {
1107+
if (!isGsapColorProperty(property)) continue;
1108+
for (const variable of cssVariableReferencesWithoutFallback(value)) {
1109+
if (definedVariables.has(variable)) continue;
1110+
const key = `${win.targetSelector}|${property}|${variable}`;
1111+
if (reported.has(key)) continue;
1112+
reported.add(key);
1113+
findings.push({
1114+
code: "gsap_undefined_css_variable",
1115+
severity: "warning",
1116+
message: `GSAP ${property} on "${win.targetSelector}" uses ${variable}, but no static CSS or composition-variable declaration defines it. The computed color may become invalid or transparent.`,
1117+
selector: win.targetSelector,
1118+
fixHint: `Define ${variable} in applicable CSS, declare "${variable.slice(2)}" in data-composition-variables, or add a var() fallback such as var(${variable}, #fff).`,
1119+
snippet: truncateSnippet(win.raw),
1120+
});
1121+
}
1122+
}
1123+
}
1124+
}
1125+
}
1126+
return findings;
1127+
},
1128+
10591129
// overlapping_gsap_tweens + gsap_animates_clip_element
10601130
// fallow-ignore-next-line complexity
10611131
async ({ source, tags, scripts, styles, rootCompositionId }) => {

0 commit comments

Comments
 (0)