Update docs to mention layout shift sources being sorted by impact area

anediaz · anediaz · commit ed6a3d4dc159 · 2025-12-04T22:10:23.000+01:00
diff --git a/index.bs b/index.bs
@@ -151,7 +151,9 @@ Source attribution {#source-attribution}
 
 In addition to the layout shift value, the API reports a sampling of up to five
 DOM elements whose layout shifts most substantially contributed to the layout
-shift value for an animation frame.
+shift value for an animation frame. The <a href="#dom-layoutshift-sources">sources</a>
+are sorted by impact area in descending order, so the first element represents
+the element that contributed most to the layout shift.
 
 It is possible that the true "root cause" of instability will be only
 indirectly related to the DOM element that experiences a layout shift.
@@ -186,6 +188,12 @@ Usage example {#example}
           timestamp: entry.startTime
         });
         cumulativeLayoutShiftScore += entry.value;
+
+        // Sources are sorted by impact area in descending order.
+        // The first element contributed most to the layout shift.
+        if (entry.sources && entry.sources.length > 0) {
+          console.log('Largest contributing element:', entry.sources[0].node);
+        }
       }
     }
 
@@ -449,6 +457,11 @@ events are also not excluding inputs.
 All attributes have the values which are assigned to them by the steps to
 <a>report the layout shift</a>.
 
+The <dfn attribute for=LayoutShift>sources</dfn> attribute returns a
+{{FrozenArray}} of {{LayoutShiftAttribution}} objects, sorted in descending order
+by impact area. The first element has the largest <a>node impact region</a> and
+represents the element that contributed most to the layout shift.
+
 A user agent implementing the Layout Instability API must include
 <code>"layout-shift"</code> in {{PerformanceObserver/supportedEntryTypes}} for
 <a href="https://html.spec.whatwg.org/multipage/window-object.html#the-window-object">Window</a>
@@ -525,7 +538,7 @@ When asked to <dfn export>report the layout shift</dfn> for an active
     1. Set |newEntry|'s <dfn attribute for=LayoutShift>hadRecentInput</dfn>
         attribute to <code>true</code> if {{LayoutShift/lastInputTime}} is less
         than 500 milliseconds in the past, and <code>false</code> otherwise.
-    1. Set |newEntry|'s <dfn attribute for=LayoutShift>sources</dfn> attribute
+    1. Set |newEntry|'s {{LayoutShift/sources}} attribute
         to the result of invoking the algorithm to <a>report the layout shift
         sources</a> for |D|.
     1. <a href="https://w3c.github.io/performance-timeline/#dfn-queue-a-performanceentry">Queue the PerformanceEntry</a>
@@ -568,6 +581,15 @@ When asked to <dfn>report the layout shift sources</dfn> for an active
             <a href="https://infra.spec.whatwg.org/#list-replace">replace</a>
             |smallest| with |N| in |C|.
 
+1. <a href="https://infra.spec.whatwg.org/#list-sort-in-descending-order">Sort</a>
+    |C| in descending order, with |a| being less than |b| if the area
+    of the <a>node impact region</a> of |a| is less than the area
+    of the <a>node impact region</a> of |b|.
+
+    NOTE: This ensures that the <a href="#dom-layoutshift-sources">sources</a>
+    attribute exposes layout shift sources in descending order by impact area,
+    with the element that contributed most to the layout shift appearing first.
+
 1. Return a {{FrozenArray}} of {{LayoutShiftAttribution}} objects created
     by running the algorithm to <a>create the attribution</a> once
     for each member of |C|.
