From ee43a00462bb30955bed8f64b35334fbe7a34a02 Mon Sep 17 00:00:00 2001 From: Florian Scholz Date: Wed, 15 Mar 2023 04:29:30 +0100 Subject: [PATCH] Document Layout Instability API (#23007) * Fix group, redirect overview page * Add layoutshift to general performance pages * Update LayoutShift pages * Apply suggestions from code review Co-authored-by: wbamberg * Fix more nodes * Expand on why hadRecentInput is useful * Avoid CLS * Fix links * tags -> status * Fix spec list * tweaks as per wbamberg --------- Co-authored-by: wbamberg --- files/en-us/_redirects.txt | 1 + .../web/api/layout_instability_api/index.md | 45 --------- .../api/layoutshift/hadrecentinput/index.md | 56 +++++++++++ files/en-us/web/api/layoutshift/index.md | 81 +++++++++------- .../api/layoutshift/lastinputtime/index.md | 54 +++++++++++ .../web/api/layoutshift/sources/index.md | 44 +++++++++ .../en-us/web/api/layoutshift/tojson/index.md | 94 +++++++++++++++++++ .../en-us/web/api/layoutshift/value/index.md | 51 ++++++++++ .../currentrect/index.md | 2 +- .../web/api/layoutshiftattribution/index.md | 8 +- .../api/layoutshiftattribution/node/index.md | 6 +- .../previousrect/index.md | 2 +- .../layoutshiftattribution/tojson/index.md | 2 +- .../en-us/web/api/performance_api/diagram.svg | 4 +- files/en-us/web/api/performance_api/index.md | 5 + .../api/performanceentry/duration/index.md | 1 + .../api/performanceentry/entrytype/index.md | 6 ++ files/en-us/web/api/performanceentry/index.md | 1 + .../web/api/performanceentry/name/index.md | 4 + .../api/performanceentry/starttime/index.md | 2 + .../api/performancelongtasktiming/index.md | 2 +- files/jsondata/GroupData.json | 9 +- files/jsondata/SpecData.json | 5 - 23 files changed, 383 insertions(+), 102 deletions(-) delete mode 100644 files/en-us/web/api/layout_instability_api/index.md create mode 100644 files/en-us/web/api/layoutshift/hadrecentinput/index.md create mode 100644 files/en-us/web/api/layoutshift/lastinputtime/index.md create mode 100644 files/en-us/web/api/layoutshift/sources/index.md create mode 100644 files/en-us/web/api/layoutshift/tojson/index.md create mode 100644 files/en-us/web/api/layoutshift/value/index.md diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt index 53a9fb6069c5edc..823549ee691a18c 100644 --- a/files/en-us/_redirects.txt +++ b/files/en-us/_redirects.txt @@ -8771,6 +8771,7 @@ /en-US/docs/Web/API/KeyframeEffectReadOnly/iterationComposite /en-US/docs/Web/API/KeyframeEffect/iterationComposite /en-US/docs/Web/API/KeyframeEffectReadOnly/target /en-US/docs/Web/API/KeyframeEffect/target /en-US/docs/Web/API/Largest_Contentful_Paint_API /en-US/docs/Web/API/LargestContentfulPaint +/en-US/docs/Web/API/Layout_Instability_API /en-US/docs/Web/API/LayoutShift /en-US/docs/Web/API/LinearAccelerationSensor/x /en-US/docs/Web/API/Accelerometer/x /en-US/docs/Web/API/LinearAccelerationSensor/y /en-US/docs/Web/API/Accelerometer/y /en-US/docs/Web/API/LinearAccelerationSensor/z /en-US/docs/Web/API/Accelerometer/z diff --git a/files/en-us/web/api/layout_instability_api/index.md b/files/en-us/web/api/layout_instability_api/index.md deleted file mode 100644 index 08a3ba361a31467..000000000000000 --- a/files/en-us/web/api/layout_instability_api/index.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Layout Instability API -slug: Web/API/Layout_Instability_API -page-type: web-api-overview -status: - - experimental -browser-compat: api.LayoutShift ---- - -{{DefaultAPISidebar("Layout Instability API")}}{{SeeCompatTable}} - -The **Layout Instability API** provides interfaces for measuring and reporting layout shifts. - -## Concepts and Usage - -A layout shift happens when any element that is visible in the viewport changes its start position between two frames. These elements are described as being **unstable**, and contribute to a poor [Cumulative Layout Shift (CLS)](https://web.dev/cls/) score, indicating a lack of visual stability. - -The Layout Instability API provides a way to measure and report on these layout shifts. All tools for debugging layout shifts, including those in DevTools, use this API. The API can also be used to observe and debug layout shifts by logging the information to the console, to send the data to a server endpoint, or to Google Analytics. - -## Interfaces - -- {{domxref("LayoutShift")}} - - : Provides insights into the stability of web pages based on movements of the elements on the page. -- {{domxref("LayoutShiftAttribution")}} - - : Provides debugging information about elements which have shifted. - -## Examples - -The following example observes all layout shifts, and prints them to the console. - -```js -new PerformanceObserver((list) => { - console.log(list.getEntries()); -}).observe({ type: "layout-shift", buffered: true }); -``` - -## Specifications - -{{Specifications}} - -## See also - -- [Cumulative Layout Shift](https://web.dev/cls/) -- [Debug layout shifts](https://web.dev/debug-layout-shifts/) -- [Debug Web Vitals in the field](https://web.dev/debug-web-vitals-in-the-field/) diff --git a/files/en-us/web/api/layoutshift/hadrecentinput/index.md b/files/en-us/web/api/layoutshift/hadrecentinput/index.md new file mode 100644 index 000000000000000..2eece379b37e7b0 --- /dev/null +++ b/files/en-us/web/api/layoutshift/hadrecentinput/index.md @@ -0,0 +1,56 @@ +--- +title: LayoutShift.hadRecentInput +slug: Web/API/LayoutShift/hadRecentInput +page-type: web-api-instance-property +browser-compat: api.LayoutShift.hadRecentInput +status: + - experimental +--- + +{{SeeCompatTable}}{{APIRef("Performance API")}} + +The **`hadRecentInput`** read-only property of the {{domxref("LayoutShift")}} interface returns `true` if {{domxref("LayoutShift.lastInputTime", "lastInputTime")}} is less than 500 milliseconds in the past. + +Layout shifts are only a problem if the user is not expecting them, so layout shifts that are the result of user interactions (such as a user expanding a UI element) are often not considered in layout shift metrics. The `hadRecentInput` property allows you to exclude these shifts. + +## Value + +A boolean returning `true` if {{domxref("LayoutShift.lastInputTime", "lastInputTime")}} is less than 500 milliseconds in the past; `false` otherwise. + +## Examples + +### Ignoring recent user input for layout shift scores + +The following example shows how the `hadRecentInput` property is used to only count layout shifts without recent user input. + +```js +const observer = new PerformanceObserver((list) => { + for (const entry of list.getEntries()) { + // Count layout shifts without recent user input only + if (!entry.hadRecentInput) { + console.log("LayoutShift value:", entry.value); + if (entry.sources) { + for (const { node, currentRect, previousRect } of entry.sources) + console.log("LayoutShift source:", node, { + currentRect, + previousRect, + }); + } + } + } +}); + +observer.observe({ type: "layout-shift", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("LayoutShift.lastInputTime")}} diff --git a/files/en-us/web/api/layoutshift/index.md b/files/en-us/web/api/layoutshift/index.md index 1cf3700336c493b..937875ca8720302 100644 --- a/files/en-us/web/api/layoutshift/index.md +++ b/files/en-us/web/api/layoutshift/index.md @@ -7,22 +7,43 @@ status: browser-compat: api.LayoutShift --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} -The `LayoutShift` interface of the [Layout Instability API](/en-US/docs/Web/API/Layout_Instability_API) provides insights into the stability of web pages based on movements of the elements on the page. +The `LayoutShift` interface of the [Performance API](/en-US/docs/Web/API/Performance_API) provides insights into the layout stability of web pages based on movements of the elements on the page. + +## Description + +A layout shift happens when any element that is visible in the viewport changes its position between two frames. These elements are described as being **unstable**, indicating a lack of visual stability. + +The Layout Instability API provides a way to measure and report on these layout shifts. All tools for debugging layout shifts, including those in the browser's developer tools, use this API. The API can also be used to observe and debug layout shifts by logging the information to the console, to send the data to a server endpoint, or to web page analytics. + +Popular performance tools, use this API to calculate a [Cumulative Layout Shift (CLS)](https://web.dev/cls/) score. {{InheritanceDiagram}} ## Instance properties +This interface extends the following {{domxref("PerformanceEntry")}} properties by qualifying them as follows: + +- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `0` (the concept of duration does not apply to layout shifts). +- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `"layout-shift"`. +- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Always returns `"layout-shift"`. +- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}} + - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the time when the layout shift started. + +This interface also supports the following properties: + - {{domxref("LayoutShift.value")}} {{Experimental_Inline}} - - : Returns the `impact fraction` (fraction of the viewport that was shifted) times the `distance fraction` (distance moved as a fraction of viewport). + - : Returns the layout shift score calculated as the impact fraction (fraction of the viewport that was shifted) multiplied by the distance fraction (distance moved as a fraction of viewport). - {{domxref("LayoutShift.hadRecentInput")}} {{Experimental_Inline}} - - : Returns `true` if there was a user input in the past 500 milliseconds. + - : Returns `true` if {{domxref("LayoutShift.lastInputTime", "lastInputTime")}} is less than 500 milliseconds in the past. - {{domxref("LayoutShift.lastInputTime")}} {{Experimental_Inline}} - - : Returns the time of the most recent user input. + - : Returns the time of the most recent excluding input (user input that would exclude this entry as a contributor to the CLS score) or `0` if no excluding input has occurred. - {{domxref("LayoutShift.sources")}} {{Experimental_Inline}} - - : Returns an array of {{domxref('LayoutShiftAttribution')}} objects with information on the elements that were shifted. + - : Returns an array of {{domxref("LayoutShiftAttribution")}} objects with information on the elements that were shifted. ## Instance methods @@ -31,39 +52,28 @@ The `LayoutShift` interface of the [Layout Instability API](/en-US/docs/Web/API/ ## Examples -The following example shows how to capture layout shifts and log them to the console. +### Logging layout shift values -Note that in this example data is only sent to the server when the user leaves the tab. +The following example shows how to capture layout shifts and log them to the console. ```js -// Catch errors since some browsers throw when using the new `type` option. -// https://webkit.org/b/209216 -try { - let cumulativeLayoutShiftScore = 0; - - const observer = new PerformanceObserver((list) => { - for (const entry of list.getEntries()) { - // Only count layout shifts without recent user input. - if (!entry.hadRecentInput) { - cumulativeLayoutShiftScore += entry.value; +const observer = new PerformanceObserver((list) => { + for (const entry of list.getEntries()) { + // Count layout shifts without recent user input only + if (!entry.hadRecentInput) { + console.log("LayoutShift value:", entry.value); + if (entry.sources) { + for (const { node, currentRect, previousRect } of entry.sources) + console.log("LayoutShift source:", node, { + currentRect, + previousRect, + }); } } - }); - - observer.observe({ type: "layout-shift", buffered: true }); - - document.addEventListener("visibilitychange", () => { - if (document.visibilityState === "hidden") { - // Force any pending records to be dispatched. - observer.takeRecords(); - observer.disconnect(); + } +}); - console.log("CLS:", cumulativeLayoutShiftScore); - } - }); -} catch (e) { - // Do nothing if the browser doesn't support this API. -} +observer.observe({ type: "layout-shift", buffered: true }); ``` ## Specifications @@ -73,3 +83,8 @@ try { ## Browser compatibility {{Compat}} + +## See also + +- {{domxref("LayoutShiftAttribution")}} +- [Cumulative Layout Shift (CLS)](https://web.dev/cls/) diff --git a/files/en-us/web/api/layoutshift/lastinputtime/index.md b/files/en-us/web/api/layoutshift/lastinputtime/index.md new file mode 100644 index 000000000000000..9605b26e5ad9e61 --- /dev/null +++ b/files/en-us/web/api/layoutshift/lastinputtime/index.md @@ -0,0 +1,54 @@ +--- +title: LayoutShift.lastInputTime +slug: Web/API/LayoutShift/lastInputTime +page-type: web-api-instance-property +browser-compat: api.LayoutShift.lastInputTime +status: + - experimental +--- + +{{SeeCompatTable}}{{APIRef("Performance API")}} + +The **`lastInputTime`** read-only property of the {{domxref("LayoutShift")}} interface returns the time of the most recent excluding input or `0` if no excluding input has occurred. + +Layout shifts are only bad if the user wasn't expecting them. Many layout shift metrics (like [Cumulative Layout Shift (CLS)](https://web.dev/cls/)) exclude shifts that occurred soon after certain user interactions. These interactions are called _excluding inputs_. Excluding inputs are: + +- Any events which signal a user's active interaction with the document: ([`mousedown`](/en-US/docs/Web/API/Element/mousedown_event), [`keydown`](/en-US/docs/Web/API/Element/keydown_event), and [`pointerdown`](/en-US/docs/Web/API/Element/pointerdown_event)) +- Any events which directly changes the size of the viewport. +- [`change`](/en-US/docs/Web/API/HTMLElement/change_event) events. + +The [`mousemove`](/en-US/docs/Web/API/Element/mousemove_event) and [`pointermove`](/en-US/docs/Web/API/Element/pointermove_event) events are **not** excluding inputs. + +## Value + +A {{domxref("DOMHighResTimeStamp")}} indicating the most recent excluding input time or `0` if no excluding input has occurred. + +## Examples + +### Logging last input times + +Log excluding input times if excluding input has occurred. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + if (entry.lastInputTime) { + console.log(entry.lastInputTime); + } + }); +}); + +observer.observe({ type: "layout-shift", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("LayoutShift.hadRecentInput")}} diff --git a/files/en-us/web/api/layoutshift/sources/index.md b/files/en-us/web/api/layoutshift/sources/index.md new file mode 100644 index 000000000000000..3cbd8de4b108248 --- /dev/null +++ b/files/en-us/web/api/layoutshift/sources/index.md @@ -0,0 +1,44 @@ +--- +title: LayoutShift.sources +slug: Web/API/LayoutShift/sources +page-type: web-api-instance-property +browser-compat: api.LayoutShift.sources +status: + - experimental +--- + +{{SeeCompatTable}}{{APIRef("Performance API")}} + +The **`sources`** read-only property of the {{domxref("LayoutShift")}} interface returns an array of {{domxref("LayoutShiftAttribution")}} objects that indicate the DOM elements that moved during the layout shift. + +## Value + +An {{jsxref("Array")}} of {{domxref("LayoutShiftAttribution")}} objects. This array will not contain more than five sources. If there are more than five elements impacted by the layout shift, the five most impactful elements are reported. + +## Examples + +### Logging layout shift sources + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + entry.sources.forEach((source) => { + console.log(source); + }); + }); +}); + +observer.observe({ type: "layout-shift", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{domxref("LayoutShiftAttribution")}} diff --git a/files/en-us/web/api/layoutshift/tojson/index.md b/files/en-us/web/api/layoutshift/tojson/index.md new file mode 100644 index 000000000000000..48bccf34bdb6630 --- /dev/null +++ b/files/en-us/web/api/layoutshift/tojson/index.md @@ -0,0 +1,94 @@ +--- +title: LayoutShift.toJSON() +slug: Web/API/LayoutShift/toJSON +page-type: web-api-instance-method +status: + - experimental +browser-compat: api.LayoutShift.toJSON +--- + +{{APIRef("Performance API")}}{{SeeCompatTable}} + +The **`toJSON()`** method of the {{domxref("LayoutShift")}} interface is a {{Glossary("Serialization","serializer")}}; it returns a JSON representation of the {{domxref("LayoutShift")}} object. + +## Syntax + +```js-nolint +toJSON() +``` + +### Parameters + +None. + +### Return value + +A {{jsxref("JSON")}} object that is the serialization of the {{domxref("LayoutShift")}} object. + +## Examples + +### Using the toJSON method + +In this example, calling `entry.toJSON()` returns a JSON representation of the `LayoutShift` object. + +```js +const observer = new PerformanceObserver((list) => { + list.getEntries().forEach((entry) => { + console.log(entry.toJSON()); + }); +}); + +observer.observe({ type: "layout-shift", buffered: true }); +``` + +This would log a JSON object like so: + +```json +{ + "name": "", + "entryType": "layout-shift", + "startTime": 246.39999999850988, + "duration": 0, + "value": 0.0071167845054842215, + "hadRecentInput": false, + "lastInputTime": 0, + "sources": [ + { + "previousRect": { + "x": 917, + "y": 708, + "width": 706, + "height": 248, + "top": 708, + "right": 1623, + "bottom": 956, + "left": 917 + }, + "currentRect": { + "x": 693, + "y": 708, + "width": 1154, + "height": 472, + "top": 708, + "right": 1847, + "bottom": 1180, + "left": 693 + } + } + ] +} +``` + +To get a JSON string, you can use [`JSON.stringify(entry)`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) directly; it will call `toJSON()` automatically. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- {{jsxref("JSON")}} diff --git a/files/en-us/web/api/layoutshift/value/index.md b/files/en-us/web/api/layoutshift/value/index.md new file mode 100644 index 000000000000000..31dd99385e7c30e --- /dev/null +++ b/files/en-us/web/api/layoutshift/value/index.md @@ -0,0 +1,51 @@ +--- +title: LayoutShift.value +slug: Web/API/LayoutShift/value +page-type: web-api-instance-property +browser-compat: api.LayoutShift.value +status: + - experimental +--- + +{{SeeCompatTable}}{{APIRef("Performance API")}} + +The **`value`** read-only property of the {{domxref("LayoutShift")}} interface returns the layout shift score calculated as the impact fraction (fraction of the viewport that was shifted) multiplied by the distance fraction (distance moved as a fraction of viewport). + +## Value + +A number between `0.0` and `1.0` indicating the layout shift score. + +It is calculated as the impact fraction (fraction of the viewport that was shifted) multiplied by the distance fraction (distance moved as a fraction of viewport). + +```plain +layout shift score = impact fraction * distance fraction +``` + +For more details, see [Layout shift score](https://web.dev/cls/#layout-shift-score) on web.dev. + +## Examples + +### Logging the entry's layout shift score + +The following example shows how use the `value` property to log the layout shift score. + +```js +const observer = new PerformanceObserver((list) => { + for (const entry of list.getEntries()) { + // Count layout shifts without recent user input only + if (!entry.hadRecentInput) { + console.log("Entry's layout shift score:", entry.value); + } + } +}); + +observer.observe({ type: "layout-shift", buffered: true }); +``` + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/web/api/layoutshiftattribution/currentrect/index.md b/files/en-us/web/api/layoutshiftattribution/currentrect/index.md index 8e4fdea16ebd06e..f3bee04db9e38d1 100644 --- a/files/en-us/web/api/layoutshiftattribution/currentrect/index.md +++ b/files/en-us/web/api/layoutshiftattribution/currentrect/index.md @@ -7,7 +7,7 @@ status: browser-compat: api.LayoutShiftAttribution.currentRect --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} The **`currentRect`** read-only property of the {{domxref("LayoutShiftAttribution")}} interface returns a {{domxref("DOMRectReadOnly")}} object representing the position of the element after the shift. diff --git a/files/en-us/web/api/layoutshiftattribution/index.md b/files/en-us/web/api/layoutshiftattribution/index.md index bb0833f86d80f47..c71a07cd7453e89 100644 --- a/files/en-us/web/api/layoutshiftattribution/index.md +++ b/files/en-us/web/api/layoutshiftattribution/index.md @@ -7,15 +7,15 @@ status: browser-compat: api.LayoutShiftAttribution --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} -The `LayoutShiftAttribution` interface of the [Layout Instability API](/en-US/docs/Web/API/Layout_Instability_API) provides debugging information about elements which have shifted. +The `LayoutShiftAttribution` interface provides debugging information about elements which have shifted. Instances of `LayoutShiftAttribution` are returned in an array by calling {{domxref("LayoutShift.sources")}}. ## Instance properties -- {{domxref("LayoutShiftAttribution.Node")}} {{ReadOnlyInline}} +- {{domxref("LayoutShiftAttribution.node")}} {{ReadOnlyInline}} - : Returns the element that has shifted (null if it has been removed). - {{domxref("LayoutShiftAttribution.previousRect")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMRectReadOnly")}} object representing the position of the element before the shift. @@ -29,7 +29,7 @@ Instances of `LayoutShiftAttribution` are returned in an array by calling {{domx ## Examples -The following example finds the element that is causing the largest layout shift, and prints that `node` to the console. For more detail on this see [Debug Web Vitals in the field](https://web.dev/debug-web-vitals-in-the-field/). +The following example finds the element with the highest layout shift score, and returns the element in that entry with the largest size prior to the shift (`previousRect`). For more detail on this see [Debug Web Vitals in the field](https://web.dev/debug-web-vitals-in-the-field/). ```js function getCLSDebugTarget(entries) { diff --git a/files/en-us/web/api/layoutshiftattribution/node/index.md b/files/en-us/web/api/layoutshiftattribution/node/index.md index 52f9d6823e7283a..7333fd5772e4e62 100644 --- a/files/en-us/web/api/layoutshiftattribution/node/index.md +++ b/files/en-us/web/api/layoutshiftattribution/node/index.md @@ -7,13 +7,13 @@ status: browser-compat: api.LayoutShiftAttribution.node --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} -The **`node`** read-only property of the {{domxref("LayoutShiftAttribution")}} interface returns a {{domxref("node")}} representing the object that has shifted. +The **`node`** read-only property of the {{domxref("LayoutShiftAttribution")}} interface returns a {{domxref("Node")}} representing the object that has shifted. ## Value -A {{domxref("node")}}. +A {{domxref("Node")}}. ## Examples diff --git a/files/en-us/web/api/layoutshiftattribution/previousrect/index.md b/files/en-us/web/api/layoutshiftattribution/previousrect/index.md index 61c346f4ba0e7a5..a3a24f324015a4d 100644 --- a/files/en-us/web/api/layoutshiftattribution/previousrect/index.md +++ b/files/en-us/web/api/layoutshiftattribution/previousrect/index.md @@ -7,7 +7,7 @@ status: browser-compat: api.LayoutShiftAttribution.previousRect --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} The **`previousRect`** read-only property of the {{domxref("LayoutShiftAttribution")}} interface returns a {{domxref("DOMRectReadOnly")}} object representing the position of the element before the shift. diff --git a/files/en-us/web/api/layoutshiftattribution/tojson/index.md b/files/en-us/web/api/layoutshiftattribution/tojson/index.md index f8f83dbcba13145..a2dedef6bb58f6d 100644 --- a/files/en-us/web/api/layoutshiftattribution/tojson/index.md +++ b/files/en-us/web/api/layoutshiftattribution/tojson/index.md @@ -7,7 +7,7 @@ status: browser-compat: api.LayoutShiftAttribution.toJSON --- -{{APIRef("Layout Instability API")}}{{SeeCompatTable}} +{{APIRef("Performance API")}}{{SeeCompatTable}} The **`toJSON()`** method of the {{domxref("LayoutShiftAttribution")}} interface is a _serializer_ that returns a JSON representation of the `LayoutShiftAttribution` object. diff --git a/files/en-us/web/api/performance_api/diagram.svg b/files/en-us/web/api/performance_api/diagram.svg index 5ccb0cefecbc6b2..e4f52791b4b3a37 100644 --- a/files/en-us/web/api/performance_api/diagram.svg +++ b/files/en-us/web/api/performance_api/diagram.svg @@ -1 +1,3 @@ -PerformanceEntryPerformanceMarkPerformanceMeasurePerformancePaintTimingPerformanceResourceTimingPerformanceNavigationTimingPerformanceElementTimingPerformanceLongTaskTimingPerformanceEventTimingTaskAttributionTimingLargestContentfulPaintPerformancePerformanceObserverText is not SVG - cannot display \ No newline at end of file + + +PerformanceEntryPerformanceMarkPerformanceMeasurePerformancePaintTimingPerformanceResourceTimingPerformanceNavigationTimingPerformanceElementTimingPerformanceLongTaskTimingPerformanceEventTimingTaskAttributionTimingLargestContentfulPaintPerformancePerformanceObserverLayoutShiftText is not SVG - cannot display \ No newline at end of file diff --git a/files/en-us/web/api/performance_api/index.md b/files/en-us/web/api/performance_api/index.md index 17009e2bb80281f..f876e6c0025f429 100644 --- a/files/en-us/web/api/performance_api/index.md +++ b/files/en-us/web/api/performance_api/index.md @@ -7,6 +7,7 @@ spec-urls: - https://w3c.github.io/event-timing/ - https://w3c.github.io/hr-time/ - https://w3c.github.io/largest-contentful-paint/ + - https://wicg.github.io/layout-instability/ - https://w3c.github.io/longtasks/ - https://w3c.github.io/navigation-timing/ - https://w3c.github.io/paint-timing/ @@ -40,6 +41,10 @@ The {{domxref("PerformanceObserver")}} interface enables you to listen for vario - : A read-only map returned by {{domxref("performance.eventCounts")}} containing the number of events which have been dispatched per event type. - {{domxref("LargestContentfulPaint")}} - : Measures the render time of the largest image or text block visible within the viewport, recorded from when the page first begins to load. +- {{domxref("LayoutShift")}} + - : Provides insights into the layout stability of web pages based on movements of the elements on the page. +- {{domxref("LayoutShiftAttribution")}} + - : Provides debugging information about elements which have shifted. - {{domxref("Performance")}} - : Main interface to access performance measurements. Available to window and worker contexts using {{domxref("performance_property", "self.performance")}}. - {{domxref("PerformanceElementTiming")}} diff --git a/files/en-us/web/api/performanceentry/duration/index.md b/files/en-us/web/api/performanceentry/duration/index.md index ef2ab165c5da5a6..e1e06173789129e 100644 --- a/files/en-us/web/api/performanceentry/duration/index.md +++ b/files/en-us/web/api/performanceentry/duration/index.md @@ -32,6 +32,7 @@ For the following entry types, `duration` is not applicable, and in this case th - `element` - `largest-contentful-paint` +- `layout-shift` - `mark` - `paint` - `taskattribution` diff --git a/files/en-us/web/api/performanceentry/entrytype/index.md b/files/en-us/web/api/performanceentry/entrytype/index.md index c282203511c0a57..f219304f5178069 100644 --- a/files/en-us/web/api/performanceentry/entrytype/index.md +++ b/files/en-us/web/api/performanceentry/entrytype/index.md @@ -39,6 +39,12 @@ A string. The return value depends on the subtype of the `PerformanceEntry` obje The entry instance will be a {{domxref("LargestContentfulPaint")}} object. +- `layout-shift` + + - : Reports layout stability of web pages based on movements of the elements on the page. + + The entry instance will be a {{domxref("LayoutShift")}} object. + - `longtask` - : Reports instances of long tasks. diff --git a/files/en-us/web/api/performanceentry/index.md b/files/en-us/web/api/performanceentry/index.md index 43d3865aec0d815..faca3ed612c9fb1 100644 --- a/files/en-us/web/api/performanceentry/index.md +++ b/files/en-us/web/api/performanceentry/index.md @@ -16,6 +16,7 @@ A performance entry can also be created by calling the {{domxref("Performance.ma The `PerformanceEntry` instances will always be one of the following subclasses: - {{domxref("LargestContentfulPaint")}} +- {{domxref("LayoutShift")}} - {{domxref("PerformanceEventTiming")}} - {{domxref("PerformanceLongTaskTiming")}} - {{domxref("PerformanceMark")}} diff --git a/files/en-us/web/api/performanceentry/name/index.md b/files/en-us/web/api/performanceentry/name/index.md index a65f09b7eb8d204..4d911357a65f41c 100644 --- a/files/en-us/web/api/performanceentry/name/index.md +++ b/files/en-us/web/api/performanceentry/name/index.md @@ -25,6 +25,10 @@ A string. The value depends on the subclass of the `PerformanceEntry` object as {{domxref('LargestContentfulPaint')}} Always returns an empty string. + + {{domxref('LayoutShift')}} + Always returns "layout-shift". + {{domxref('PerformanceElementTiming')}} One of the following strings: diff --git a/files/en-us/web/api/performanceentry/starttime/index.md b/files/en-us/web/api/performanceentry/starttime/index.md index 7dbe908c5e7dcbc..527d3c1c00fe6c2 100644 --- a/files/en-us/web/api/performanceentry/starttime/index.md +++ b/files/en-us/web/api/performanceentry/starttime/index.md @@ -24,6 +24,8 @@ The meaning of this property depends on the value of this performance entry's {{ - : The time the first input event was created, i.e. that event's [`timeStamp`](/en-US/docs/Web/API/Event/timeStamp). - `largest-contentful-paint` - : The value of this entry's {{domxref("LargestContentfulPaint.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("LargestContentfulPaint.loadTime", "loadTime")}}. +- `layout-shift` + - : The time when the layout shift started. - `longtask` - : The time when the task started. - `mark` diff --git a/files/en-us/web/api/performancelongtasktiming/index.md b/files/en-us/web/api/performancelongtasktiming/index.md index 08b780a4460b864..5daa86face2a9f2 100644 --- a/files/en-us/web/api/performancelongtasktiming/index.md +++ b/files/en-us/web/api/performancelongtasktiming/index.md @@ -38,7 +38,7 @@ For tasks that don't occur within the top-level page and for figuring out which ## Instance properties -This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows: +This interface extends the following {{domxref("PerformanceEntry")}} properties for long task timing performance entry types by qualifying them as follows: - {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}} - : Returns a {{domxref("DOMHighResTimeStamp")}} representing the elapsed time between the start and end of the task, with a 1ms granularity. diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index c419e72232d5da3..9aa9f6c0600cfc5 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -806,13 +806,6 @@ "properties": ["Window.launchQueue"], "events": [] }, - "Layout Instability API": { - "overview": ["Layout Instability API"], - "interfaces: ": ["LayoutShift", "LayoutShiftAttribution"], - "methods": [], - "properties": [], - "events": [] - }, "Local Font Access API": { "overview": ["Local Font Access API"], "interfaces": ["FontData"], @@ -987,6 +980,8 @@ "interfaces": [ "EventCounts", "LargestContentfulPaint", + "LayoutShift", + "LayoutShiftAttribution", "Performance", "PerformanceEntry", "PerformanceElementTiming", diff --git a/files/jsondata/SpecData.json b/files/jsondata/SpecData.json index 0724831b22b7688..12e5fcc0cb807b7 100644 --- a/files/jsondata/SpecData.json +++ b/files/jsondata/SpecData.json @@ -1089,11 +1089,6 @@ "url": "https://wicg.github.io/largest-contentful-paint/", "status": "ED" }, - "Layout Instability": { - "name": "Layout Instability API", - "url": "https://wicg.github.io/layout-instability/", - "status": "ED" - }, "Legacy RegExp features": { "name": "Legacy RegExp features in JavaScript", "url": "https://github.com/tc39/proposal-regexp-legacy-features/",