Skip to content

Commit ad6771c

Browse files
feat(lint): warn when a scene's styles sit outside its template (#6317)
A sub-composition file with a <template> is mounted from the template alone, so a <style> in its <head> (or a stylesheet link in its body) never applies in preview, snapshot or render. Warn on it, with the fix in the message: move it inside <template>.
1 parent 7b76377 commit ad6771c

3 files changed

Lines changed: 89 additions & 2 deletions

File tree

‎docs/reference/lint-rules.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,14 @@ Source: `packages/lint/src/rules/composition.ts`.
198198

199199
**Fix:** Give the root `id="root"` and style it with `#root` plus plain descendant selectors.
200200

201+
### `subcomposition_style_outside_template`
202+
203+
**Warning.** A sub-composition file with a `<template>` has a `<style>`, or a `<link rel="stylesheet">`
204+
outside `<head>`, that sits outside the template. Mounting keeps only the template's content and the
205+
stylesheet links in `<head>`, so those styles never apply in preview, snapshot or render.
206+
207+
**Fix:** Move it inside `<template>`, next to the composition root.
208+
201209
### `template_literal_selector`
202210

203211
**Error.** `querySelector` is called with a template-literal variable, which the bundler's CSS parser crashes on.

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -804,6 +804,56 @@ describe("composition rules", () => {
804804
});
805805
});
806806

807+
describe("subcomposition_style_outside_template", () => {
808+
const scene = (head: string, beforeTemplate = "", inTemplate = "") => `<!doctype html>
809+
<html><head>${head}</head><body>${beforeTemplate}
810+
<template id="scene-template">${inTemplate}
811+
<div data-composition-id="scene" data-width="1920" data-height="1080"></div>
812+
</template>
813+
</body></html>`;
814+
const findings = async (html: string, isSubComposition = true) =>
815+
(await lintHyperframeHtml(html, { isSubComposition })).findings.filter(
816+
(f) => f.code === "subcomposition_style_outside_template",
817+
);
818+
819+
it("warns on a head <style> the mount drops, and says to move it inside <template>", async () => {
820+
const found = await findings(scene("<style>.title { color: red; }</style>"));
821+
expect(found).toHaveLength(1);
822+
expect(found[0]?.severity).toBe("warning");
823+
expect(found[0]?.fixHint).toContain("Move it inside <template>");
824+
expect(found[0]?.snippet).toContain("<style>");
825+
});
826+
827+
it("warns on a <style> or stylesheet link in the body outside <template>", async () => {
828+
const found = await findings(
829+
scene("", '<style>.a { color: red; }</style><link rel="stylesheet" href="scene.css">'),
830+
);
831+
expect(found.map((f) => f.snippet)).toEqual([
832+
"<style>",
833+
'<link rel="stylesheet" href="scene.css">',
834+
]);
835+
});
836+
837+
it("does not warn on styles inside <template> or a stylesheet link in <head>", async () => {
838+
const html = scene(
839+
'<link rel="stylesheet" href="fonts.css">',
840+
"",
841+
'<style>.a { color: red; }</style><link rel="stylesheet" href="scene.css">',
842+
);
843+
expect(await findings(html)).toEqual([]);
844+
});
845+
846+
it("does not warn without a <template> or outside a sub-composition", async () => {
847+
const head = "<style>.a { color: red; }</style>";
848+
expect(
849+
await findings(
850+
`<html><head>${head}</head><body><div data-composition-id="scene"></div></body></html>`,
851+
),
852+
).toEqual([]);
853+
expect(await findings(scene(head), false)).toEqual([]);
854+
});
855+
});
856+
807857
describe("requestanimationframe_in_composition", () => {
808858
it("flags requestAnimationFrame usage in script content", async () => {
809859
const html = `

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

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@ import selectorParser from "postcss-selector-parser";
33
import {
44
findHtmlTag,
55
extractTimelineRegistryKeys,
6+
parseHtmlStructure,
67
readAttr,
78
readDecodedAttr,
89
readJsonAttr,
910
stripCssComments,
11+
stripHtmlComments,
1012
stripJsComments,
1113
stripJsCode,
1214
truncateSnippet,
@@ -732,16 +734,20 @@ function declaredIdsForBindingCheck(tags: readonly OpenTag[]): Set<string> | nul
732734
return declared;
733735
}
734736

735-
function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean {
737+
function isInsideTag(tag: OpenTag, tags: readonly OpenTag[], name: string): boolean {
736738
return tags.some(
737739
(candidate) =>
738-
candidate.name === "template" &&
740+
candidate.name === name &&
739741
candidate.closeIndex != null &&
740742
tag.index > candidate.index &&
741743
tag.index < candidate.closeIndex,
742744
);
743745
}
744746

747+
function isInsideInertTemplate(tag: OpenTag, tags: readonly OpenTag[]): boolean {
748+
return isInsideTag(tag, tags, "template");
749+
}
750+
745751
// `(?<![\w-])` not `\b`: the hyphen in a custom property is a word break, so a
746752
// plain boundary matches `--z-index: -1` and `--panel-z-index: -1`, which
747753
// declare variables and stack nothing. `-0` is excluded because it is not a
@@ -1536,6 +1542,29 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
15361542
];
15371543
},
15381544

1545+
// subcomposition_style_outside_template
1546+
// Mounting keeps only the <template> content and the <head> stylesheet links.
1547+
({ rawSource, options }) => {
1548+
if (!options.isSubComposition) return [];
1549+
const { tags } = parseHtmlStructure(stripHtmlComments(rawSource));
1550+
if (!tags.some((tag) => tag.name === "template")) return [];
1551+
const dropped = tags.filter((tag) => {
1552+
if (isInsideInertTemplate(tag, tags)) return false;
1553+
if (tag.name === "style") return true;
1554+
const rel = (readAttr(tag.raw, "rel") || "").toLowerCase().split(/\s+/);
1555+
return tag.name === "link" && rel.includes("stylesheet") && !isInsideTag(tag, tags, "head");
1556+
});
1557+
return dropped.map((tag) => ({
1558+
code: "subcomposition_style_outside_template",
1559+
severity: "warning" as const,
1560+
message:
1561+
`<${tag.name}> sits outside this sub-composition's <template>. Mounting keeps only the template's ` +
1562+
"content, so these styles never apply in preview, snapshot or render.",
1563+
fixHint: "Move it inside <template>, next to the composition root.",
1564+
snippet: truncateSnippet(tag.raw),
1565+
}));
1566+
},
1567+
15391568
// root_composition_missing_duration_source
15401569
//
15411570
// The render engine (packages/engine/src/services/frameCapture.ts) needs a

0 commit comments

Comments
 (0)