Update docs to mention layout shift sources being sorted by impact area #126
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
mmocny
approved these changes
Dec 2, 2025
Collaborator
mmocny
left a comment
There was a problem hiding this comment.
Thanks for also updating MDN, and the examples here.
Collaborator
|
I've approved this but I'm not a maintainer of this wicg repo-- I'll talk to @yoavweiss |
Collaborator
|
@anediaz -- the build is failing with some errors I think the main one is: Could you try to fix that first? |
aarongable
pushed a commit
to chromium/chromium
that referenced
this pull request
Dec 4, 2025
Sort the LayoutShift.sources array by per-source impact area in descending order (largest first). LayoutShift.sources currently returns up to five sources in an undefined order. This makes it difficult for diagnostics and tooling to reliably identify the most impactful contributor to a layout shift. Sorting ensures that sources[0] always corresponds to the largest impact area. Impact area is computed as the union of previousRect and currentRect for each source, matching the semantics used by Cumulative Layout Shift (CLS) calculation. This provides a deterministic ordering and makes the API more meaningful for users. The WICG spec PR: WICG/layout-instability#126 Bug: 450950606 Change-Id: Iec3530250a8c29f44203f0e17b7789806323dd48 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7196706 Commit-Queue: Ane Diaz De Tuesta <[email protected]> Reviewed-by: Michal Mocny <[email protected]> Reviewed-by: Scott Haseley <[email protected]> Cr-Commit-Position: refs/heads/main@{#1554088}
chromium-wpt-export-bot
pushed a commit
to web-platform-tests/wpt
that referenced
this pull request
Dec 4, 2025
Sort the LayoutShift.sources array by per-source impact area in descending order (largest first). LayoutShift.sources currently returns up to five sources in an undefined order. This makes it difficult for diagnostics and tooling to reliably identify the most impactful contributor to a layout shift. Sorting ensures that sources[0] always corresponds to the largest impact area. Impact area is computed as the union of previousRect and currentRect for each source, matching the semantics used by Cumulative Layout Shift (CLS) calculation. This provides a deterministic ordering and makes the API more meaningful for users. The WICG spec PR: WICG/layout-instability#126 Bug: 450950606 Change-Id: Iec3530250a8c29f44203f0e17b7789806323dd48 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7196706 Commit-Queue: Ane Diaz De Tuesta <[email protected]> Reviewed-by: Michal Mocny <[email protected]> Reviewed-by: Scott Haseley <[email protected]> Cr-Commit-Position: refs/heads/main@{#1554088}
chromium-wpt-export-bot
pushed a commit
to web-platform-tests/wpt
that referenced
this pull request
Dec 4, 2025
Sort the LayoutShift.sources array by per-source impact area in descending order (largest first). LayoutShift.sources currently returns up to five sources in an undefined order. This makes it difficult for diagnostics and tooling to reliably identify the most impactful contributor to a layout shift. Sorting ensures that sources[0] always corresponds to the largest impact area. Impact area is computed as the union of previousRect and currentRect for each source, matching the semantics used by Cumulative Layout Shift (CLS) calculation. This provides a deterministic ordering and makes the API more meaningful for users. The WICG spec PR: WICG/layout-instability#126 Bug: 450950606 Change-Id: Iec3530250a8c29f44203f0e17b7789806323dd48 Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/7196706 Commit-Queue: Ane Diaz De Tuesta <[email protected]> Reviewed-by: Michal Mocny <[email protected]> Reviewed-by: Scott Haseley <[email protected]> Cr-Commit-Position: refs/heads/main@{#1554088}
0252b44 to
ed6a3d4
Compare
Author
Thanks for the help! It seems to be passing now :-) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Define the ordering of
LayoutShift.sourcesto be sorted by impact area in descending order.This ensures that the element which contributed most to the layout shift appears first in the array.
Motivation
This change aligns the specification with:
Without this clarification, developers cannot rely on any consistent ordering of the
sourcesarray, making it harder to programmatically identify the most impactful elements causing layout shifts.Changes
This PR adds explicit documentation and normative algorithm steps to specify that layout shift sources are sorted by impact area:
sourcesare sorted by impact area in descending orderPreview | Diff