Skip to content

Commit f35c9d5

Browse files
fix(lint): condition the negative-z message on the stacking context
Review nit, confirmed on rendered pixels rather than accepted on report. The message asserted unconditionally that a negative z-index "is silently dropped". That is false whenever any ancestor forms a stacking context, which is a broad class of ordinary authoring. Measured at 0.8.72 on one frame carrying the same `z-index: -1` band under six different triggers: isolation:isolate PRESENT, full coverage transform PRESENT, full coverage opacity below 1 PRESENT, full coverage filter PRESENT, full coverage contain:paint PRESENT, full coverage will-change PRESENT, full coverage no stacking context ABSENT, zero coverage <- the #4366 shape That is ordinary CSS painting order: a negative-z child paints above its stacking context root's own background, so only the root case is hidden. The reviewer named `isolation: isolate`; the mechanism is any stacking context. This rule matches CSS TEXT and does not resolve the cascade, so it cannot know whether an ancestor forms one and will fire on both shapes. The message is therefore now CONDITIONAL rather than an assertion of absence — an unconditional claim is false for every isolated case, and a lint message that overclaims is how authors learn to disregard the rule. The measurement also produced a better `fixHint`: giving the parent a stacking context is a real remedy and was not previously offered, only DOM reordering was. Two tests pin the correction; restoring the unconditional wording fails exactly those two. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent b806b2b commit f35c9d5

2 files changed

Lines changed: 53 additions & 3 deletions

File tree

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2205,6 +2205,37 @@ ${body}
22052205
expect(finding?.message).toContain("z-index: -1");
22062206
});
22072207

2208+
// Reviewed nit, confirmed on rendered pixels at 0.8.72: the element is only
2209+
// dropped when its nearest ancestor stacking context is the composition root.
2210+
// One frame carried the same `z-index: -1` band under isolation:isolate,
2211+
// transform, opacity<1, filter, contain:paint and will-change -- all six
2212+
// PRESENT at full coverage, the no-stacking-context control ABSENT at zero.
2213+
// This rule matches CSS text and cannot resolve the cascade, so it fires on
2214+
// both shapes; the message must therefore stay conditional.
2215+
it("states the stacking-context CONDITION rather than asserting absence", async () => {
2216+
const result = await lintHyperframeHtml(
2217+
wrap(
2218+
"#under { position:absolute; z-index: -1; }",
2219+
` <div id="under" class="clip" data-start="0" data-duration="1"></div>`,
2220+
),
2221+
);
2222+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2223+
expect(finding?.message).toContain("unless an ancestor forms a stacking context");
2224+
expect(finding?.message).not.toContain("is silently dropped");
2225+
});
2226+
2227+
it("offers a stacking context as the measured remedy, not only DOM reordering", async () => {
2228+
const result = await lintHyperframeHtml(
2229+
wrap(
2230+
"#under { position:absolute; z-index: -1; }",
2231+
` <div id="under" class="clip" data-start="0" data-duration="1"></div>`,
2232+
),
2233+
);
2234+
const finding = result.findings.find((f) => f.code === "negative_z_index");
2235+
expect(finding?.fixHint).toContain("isolation: isolate");
2236+
expect(finding?.fixHint).toContain("DOM order");
2237+
});
2238+
22082239
it("flags a negative z-index in an inline style attribute", async () => {
22092240
const result = await lintHyperframeHtml(
22102241
wrap(

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

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -298,11 +298,14 @@ function negativeZIndexFinding(
298298
severity: "warning",
299299
...(selector ? { selector } : {}),
300300
message:
301-
`\`z-index: -${level}\` is silently dropped: the element does not appear in ` +
302-
"`snapshot` or `render` output, with no error and a zero exit code. " +
301+
`\`z-index: -${level}\` is dropped unless an ancestor forms a stacking context: the element then does not ` +
302+
"appear in `snapshot` or `render` output, with no error and a zero exit code. " +
303303
"Siblings at `z-index: 0` or above are unaffected.",
304304
fixHint:
305-
"Express paint order through DOM order instead - an earlier sibling paints behind a " +
305+
"Give the element's parent a stacking context - `isolation: isolate` is the cheapest, and " +
306+
"`transform`, `filter`, `opacity` below 1, `contain: paint` and `will-change` all work too. " +
307+
"The negative-z child then paints above that parent's background and renders normally. " +
308+
"Or express paint order through DOM order - an earlier sibling paints behind a " +
306309
"later one - and raise the elements that should sit in front rather than lowering this one.",
307310
snippet: truncateSnippet(match[0]),
308311
};
@@ -705,6 +708,22 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
705708
// and report nothing, so the first suspicion falls on the author's own CSS.
706709
// A warning rather than an error: whether negative stacking is in scope for
707710
// the renderer is a design decision and is not settled here.
711+
//
712+
// THE CONDITION IS LOAD-BEARING AND THE MESSAGE STATES IT. The element is only
713+
// dropped when its nearest ancestor stacking context is the composition root,
714+
// which is the shape #4366 reports. Give any ancestor a stacking context and it
715+
// renders correctly: measured at 0.8.72 on ONE frame carrying the same
716+
// `z-index: -1` band under six triggers -- isolation:isolate, transform,
717+
// opacity below 1, filter, contain:paint, will-change -- all six PRESENT at full
718+
// coverage, against the no-stacking-context control ABSENT at zero coverage.
719+
// That is ordinary CSS painting order: a negative-z child paints above its
720+
// stacking context root's own background, so only the root case is hidden.
721+
//
722+
// This rule matches CSS TEXT and does not resolve the cascade, so it cannot know
723+
// whether an ancestor forms a stacking context and fires on both shapes. That is
724+
// why the message is CONDITIONAL rather than an assertion of absence: an
725+
// unconditional "silently dropped" is false for every isolated case, and a lint
726+
// message that overclaims is how authors learn to disregard the rule.
708727
({ tags, styles }) => {
709728
const findings: HyperframeLintFinding[] = [];
710729
for (const style of styles) {

0 commit comments

Comments
 (0)