Update Element Timing API pages

files/en-us/_redirects.txt

@@ -8075,6 +8075,7 @@
 /en-US/docs/Web/API/ElementTraversal.lastElementChild	/en-US/docs/Web/API/Element/lastElementChild
 /en-US/docs/Web/API/ElementTraversal.nextElementSibling	/en-US/docs/Web/API/Element/nextElementSibling
 /en-US/docs/Web/API/ElementTraversal.previousElementSibling	/en-US/docs/Web/API/Element/previousElementSibling
+/en-US/docs/Web/API/Element_Timing_API	/en-US/docs/Web/API/PerformanceElementTiming
 /en-US/docs/Web/API/EncryptedMediaExtensions	/en-US/docs/Web/API/Encrypted_Media_Extensions_API
 /en-US/docs/Web/API/EncryptedMediaExtensions_API	/en-US/docs/Web/API/Encrypted_Media_Extensions_API
 /en-US/docs/Web/API/Entry	/en-US/docs/Web/API/FileSystemEntry

files/en-us/web/api/element/elementtiming/index.md

@@ -0,0 +1,50 @@
+---
+title: Element.elementTiming
+slug: Web/API/Element/elementTiming
+page-type: web-api-instance-property
+browser-compat: api.Element.elementTiming
+---
+
+{{DefaultAPISidebar("DOM")}}
+
+The **`elementTiming`** property of the {{domxref("Element")}} interface reflects the value of the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute which marks an element for observation in the {{domxref("PerformanceElementTiming")}} API.
+
+## Value
+
+A string.
+
+## Examples
+
+### Logging the value of `elementTiming`
+
+In this example, adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute to the {{HTMLElement("img")}} element sets the image to be observed.
+
+```html
+<img
+  src="image.jpg"
+  alt="a nice image"
+  elementtiming="big-image"
+  id="myImage" />
+```
+
+You can get the string value of the `elementtiming` HTML attribute by calling `el.elementTiming`.
+
+```js
+const el = document.getElementById("myImage");
+console.log(el.elementTiming); // "big-image"
+```
+
+For a more complete example on how to use the Element Timing API, see {{domxref("PerformanceElementTiming")}}.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- {{domxref("PerformanceElementTiming")}}
+- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) HTML attribute

files/en-us/web/api/element/index.md

@@ -47,6 +47,8 @@ _`Element` inherits properties from its parent interface, {{DOMxRef("Node")}}, a
   - : Returns a number representing the width of the top border of the element.
 - {{DOMxRef("Element.clientWidth")}} {{ReadOnlyInline}}
   - : Returns a number representing the inner width of the element.
+- {{DOMxRef("Element.elementTiming")}}
+  - : A string reflecting the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute which marks an element for observation in the {{domxref("PerformanceElementTiming")}} API.
 - {{domxref("Element.firstElementChild")}} {{ReadOnlyInline}}
   - : Returns the first child element of this element.
 - {{DOMxRef("Element.id")}}

files/en-us/web/api/performanceelementtiming/element/index.md

@@ -14,16 +14,17 @@ browser-compat: api.PerformanceElementTiming.element
 
 {{APIRef("Performance API")}}{{SeeCompatTable}}
 
-The **`element`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns an {{domxref("Element")}} which is a literal representation of the associated element.
+The **`element`** read-only property of the {{domxref("PerformanceElementTiming")}} interface returns an {{domxref("Element")}} which is a pointer to the observed element.
 
 ## Value
 
-An {{domxref("Element")}}.
+An {{domxref("Element")}} or {{jsxref("null")}} if the element is a [shadow DOM](/en-US/docs/Web/Web_Components/Using_shadow_DOM) element.
 
 ## Examples
 
-In this example calling `entry.element` will log to the console
-`<img src="image.jpg" alt="a nice image" elementtiming="big-image">`.
+### Logging the observed element
+
+In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The DOM element that is observed is logged to the console.
 
 ```html
 <img src="image.jpg" alt="a nice image" elementtiming="big-image" />
@@ -37,11 +38,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/performanceelementtiming/id/index.md

@@ -22,7 +22,9 @@ A string.
 
 ## Examples
 
-In this example calling `entry.id` will log to the console `myImage`, this being the {{htmlattrxref("id")}} of the image element.
+### Using `id`
+
+In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. It will log `myImage` to the console, this being the {{htmlattrxref("id")}} of the image element.
 
 ```html
 <img
@@ -40,11 +42,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/performanceelementtiming/identifier/index.md

@@ -22,7 +22,9 @@ A string.
 
 ## Examples
 
-In this example the value of [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) is `big-image`. Calling `entry.identifier` therefore returns the string `big-image`.
+### Using `identifier`
+
+In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The value of [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) is `big-image`. Calling `entry.identifier` therefore returns the string `big-image`.
 
 ```html
 <img
@@ -40,11 +42,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/performanceelementtiming/index.md

@@ -13,12 +13,41 @@ browser-compat: api.PerformanceElementTiming
 
 {{APIRef("Performance API")}}{{SeeCompatTable}}
 
-The **`PerformanceElementTiming`** interface of the {{domxref('Element Timing API','','',' ')}} reports timing information on a specific element identified by the page author. For example it could report timing information about the main image in an article.
+The **`PerformanceElementTiming`** interface contains render timing information for image and text node elements the developer annotated with an [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute for observation.
+
+## Description
+
+The aim of the Element Timing API is to give web developers or analytics tools the ability to measure rendering timestamps of critical elements on a page.
+
+The API supports timing information on the following elements:
+
+- {{htmlelement("img")}} elements,
+- {{SVGElement("image")}} elements inside an {{SVGElement("svg")}},
+- [poster](/en-US/docs/Web/HTML/Element/video#attr-poster) images of {{htmlelement("video")}} elements,
+- elements which have a {{cssxref("background-image")}}, and
+- groups of text nodes, such as a {{htmlelement("p")}}.
+
+The author flags an element for observation by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute on the element.
+
+`PerformanceElementTiming` inherits from {{domxref("PerformanceEntry")}}.
 
 {{InheritanceDiagram}}
 
 ## Instance properties
 
+This interface extends the following {{domxref("PerformanceEntry")}} properties for event timing performance entry types by qualifying them as follows:
+
+- {{domxref("PerformanceEntry.duration")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `0` as `duration` does not apply to this interface.
+- {{domxref("PerformanceEntry.entryType")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Always returns `"element"`.
+- {{domxref("PerformanceEntry.name")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns `"image-paint"` for images and `"text-paint"` for text.
+- {{domxref("PerformanceEntry.startTime")}} {{ReadOnlyInline}} {{Experimental_Inline}}
+  - : Returns the value of this entry's {{domxref("PerformanceElementTiming.renderTime", "renderTime")}} if it is not `0`, otherwise the value of this entry's {{domxref("PerformanceElementTiming.loadTime", "loadTime")}}.
+
+This interface also supports the following properties:
+
 - {{domxref("PerformanceElementTiming.element")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : An {{domxref("Element")}} representing the element we are returning information about.
 - {{domxref("PerformanceElementTiming.id")}} {{ReadOnlyInline}} {{Experimental_Inline}}
@@ -45,9 +74,9 @@ The **`PerformanceElementTiming`** interface of the {{domxref('Element Timing AP
 
 ## Examples
 
-In this example we have two elements which are being observed. We use the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case observing the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
+### Observing render time of specific elements
 
-Two entries will be output to the console. The first containing details of the image, the second with details of the text node.
+In this example two elements are being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation.
 
 ```html
 <img src="image.jpg" elementtiming="big-image" />
@@ -57,16 +86,22 @@ Two entries will be output to the console. The first containing details of the i
 ```js
 const observer = new PerformanceObserver((list) => {
   list.getEntries().forEach((entry) => {
-      console.log(entry);
+    console.log(entry);
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
+Two entries will be output to the console. The first containing details of the image, the second with details of the text node.
+
 ## Specifications
 
 {{Specifications}}
 
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) HTML attribute

files/en-us/web/api/performanceelementtiming/intersectionrect/index.md

@@ -24,7 +24,9 @@ For display images this is the display rectangle of the image within the viewpor
 
 ## Examples
 
-In this example calling `entry.intersectionRect` returns a {{domxref("DOMRectReadOnly")}} object with the display rectangle of the image.
+### Logging `intersectionRect`
+
+In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. Calling `entry.intersectionRect` returns a {{domxref("DOMRectReadOnly")}} object with the display rectangle of the image.
 
 ```html
 <img
@@ -42,11 +44,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/performanceelementtiming/loadtime/index.md

@@ -14,15 +14,17 @@ browser-compat: api.PerformanceElementTiming.loadTime
 
 {{APIRef("Performance API")}}{{SeeCompatTable}}
 
-The **`loadTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface always returns 0 for text. For images it returns the time which is the latest between the time the image resource is loaded and the time it is attached to the element.
+The **`loadTime`** read-only property of the {{domxref("PerformanceElementTiming")}} interface always returns `0` for text. For images it returns the time which is the latest between the time the image resource is loaded and the time it is attached to the element.
 
 ## Value
 
-A {{domxref("DOMHighResTimeStamp")}} with the loadTime of the element.
+A {{domxref("DOMHighResTimeStamp")}} with the `loadTime` of the element. Always `0` for text.
 
 ## Examples
 
-In this example calling `entry.loadTime` returns the loadTime of the image element.
+### Logging `loadTime`
+
+In this example an {{HTMLElement("img")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"`. The `buffered` flag is used to access data from before the observer was created. Calling `entry.loadTime` returns the loadTime of the image element.
 
 ```html
 <img
@@ -40,11 +42,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/performanceelementtiming/naturalheight/index.md

@@ -18,11 +18,13 @@ The **`naturalHeight`** read-only property of the {{domxref("PerformanceElementT
 
 ## Value
 
-An unsigned 32-bit integer (unsigned long) which is the intrinsic height of the image if this is applied to an image, 0 for text.
+An unsigned 32-bit integer (unsigned long) which is the intrinsic height of the image if this is applied to an image, `0` for text.
 
 ## Examples
 
-In this example the image file has a width of 1000px and a height of 750px. Calling `entry.naturalHeight` returns `750`, that being the intrinsic height in pixels.
+### Logging `naturalHeight`
+
+In this example an {{HTMLElement("image")}} element is being observed by adding the [`elementtiming`](/en-US/docs/Web/HTML/Attributes/elementtiming) attribute. A {{domxref("PerformanceObserver")}} is registered to get all performance entries of type `"element"` and the `buffered` flag is used to access data from before observer creation. The image file has a width of 1000px and a height of 750px. Calling `entry.naturalHeight` returns `750`, that being the intrinsic height in pixels.
 
 ```html
 <img
@@ -40,11 +42,9 @@ const observer = new PerformanceObserver((list) => {
     }
   });
 });
-observer.observe({ entryTypes: ["element"] });
+observer.observe({ type: "element", buffered: true });
 ```
 
-> **Note:** This example uses the {{domxref("PerformanceObserver")}} interface to create a list of performance measurement events. In our case we observe the {{domxref("PerformanceEntry.entrytype")}} `element` in order to use the `PerformanceElementTiming` interface.
-
 ## Specifications
 
 {{Specifications}}