Better exposition of computedStyleMap() and getComputedStyle() differences (#38214)

* Better exposition of computedStyleMap() and getComputedStyle() differences

* Fixes

* Update index.md

* Update index.md

* Update files/en-us/web/api/window/getcomputedstyle/index.md

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Address reviews

* Add see also

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: Josh-Cena

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

@@ -25,10 +25,14 @@ None.
 
 ### Return value
 
-A {{domxref("StylePropertyMapReadOnly")}} interface.
+A {{domxref("StylePropertyMapReadOnly")}} object.
+
+Unlike {{domxref("Window.getComputedStyle")}}, the return value contains [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), not [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value). For most properties, they are the same, except a few layout-related properties, where the resolved value is the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) instead of the computed value. See the [comparison with `getComputedStyle()`](#comparison_with_getcomputedstyle) example for details.
 
 ## Examples
 
+### Getting default styles
+
 We start with some simple HTML: a paragraph with a link, and a definition list to which
 we will add all the CSS Property / Value pairs.
 
@@ -79,16 +83,68 @@ In [browsers that support `computedStyleMap()`](#browser_compatibility),
 you'll see a list of all the CSS properties and values.
 In other browsers you'll just see a link.
 
-{{EmbedLiveSample("Examples", 300, 300)}}
+{{EmbedLiveSample("getting_default_styles", 300, 300)}}
 
 Did you realize how many default CSS properties a link had? Update the `document.querySelector("a")`
 to `document.querySelector("p")`, and you'll notice a difference in the `margin-top`
 and `margin-bottom` default computed values.
 
+### Comparison with getComputedStyle()
+
+{{domxref("Window.getComputedStyle()")}} returns [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value), while `computedStyleMap()` returns [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value). These are usually the same, but for some properties, the resolved value is the [used value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value) instead of the computed value. For example, percentage values for widths are resolved to pixel values _post-layout_, so the used values are in pixels, while the computed values are still in percentages.
+
+Note that the way we present it makes the two APIs seem more similar than they are. `computedStyleMap()` contains [CSS Typed OM](/en-US/docs/Web/API/CSS_Typed_OM_API) objects, while `getComputedStyle()` contains strings. The former presents the same information in a more structured and processable way.
+
+In this example, the `width` property is specified as a percentage, so the computed value is given as a percentage, but the resolved value is given in pixels. The `height` is always in pixels. The `background-color` is a named color, but it is computed to an RGB value.
+
+```html
+<div class="container">
+  <div class="item"></div>
+</div>
+<pre id="result"></pre>
+```
+
+```css
+.container {
+  width: 200px;
+  height: 200px;
+}
+
+.item {
+  width: 50%;
+  height: 100px;
+  background-color: tomato;
+}
+```
+
+```js
+const item = document.querySelector(".item");
+const result = document.querySelector("#result");
+const resolvedValues = getComputedStyle(item);
+const computedValues = item.computedStyleMap();
+
+result.textContent = `resolvedValues.width = ${resolvedValues.width}
+computedValues.get("width") = ${computedValues.get("width")}
+
+resolvedValues.height = ${resolvedValues.height}
+computedValues.get("height") = ${computedValues.get("height")}
+
+resolvedValues.backgroundColor = ${resolvedValues.backgroundColor}
+computedValues.get("background-color") = ${computedValues.get(
+  "background-color",
+)}`;
+```
+
+{{EmbedLiveSample("comparison_with_getcomputedstyle", "", 350)}}
+
 ## Specifications
 
 {{Specifications}}
 
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Window.getComputedStyle()")}}

files/en-us/web/api/window/getcomputedstyle/index.md

@@ -13,8 +13,7 @@ The
 containing the values of all CSS properties of an element, after applying active
 stylesheets and resolving any basic computation those values may contain.
 
-Individual CSS property values are accessed through APIs provided by the object, or by
-indexing with CSS property names.
+Individual CSS property values are accessed through APIs provided by the returned {{DOMxRef("CSSStyleDeclaration")}} object, or by indexing with CSS property names. The values returned by `getComputedStyle` are [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value).
 
 ## Syntax
 
@@ -33,8 +32,20 @@ getComputedStyle(element, pseudoElt)
 
 ### Return value
 
-A _live_ {{DOMxRef("CSSStyleDeclaration")}}
-object, which updates automatically when the element's styles are changed.
+A _live_ {{DOMxRef("CSSStyleDeclaration")}} object, which updates automatically when the element's styles are changed.
+
+Note that:
+
+- The returned {{DOMxRef("CSSStyleDeclaration")}} object contains active values for CSS property _longhand_ names as well as shorthand names. For example, the returned object contains entries for {{cssxref("border-bottom-width")}} in addition to the {{cssxref("border-width")}} and {{cssxref("border")}} [shorthand property names](/en-US/docs/Web/CSS/Shorthand_properties).
+- Returned values are sometimes deliberately inaccurate. To avoid the "CSS History Leak" security issue, browsers may lie about the computed styles for a visited link, returning values as if the user never visited the linked URL. See [Plugging the CSS history leak](https://blog.mozilla.org/security/2010/03/31/plugging-the-css-history-leak/) and [Privacy-related changes coming to CSS `:visited`](https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/) for examples of how this is implemented.
+- During [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions), `getComputedStyle` returns the original property value in Firefox, but the final property value in WebKit.
+- In Firefox, properties with the value `auto` return the used value, not the value `auto`. So if you apply `top:auto` and `bottom:0` on an element with `height:30px` and a containing block of `height:100px`, Firefox's computed style for `top` returns `70px`, as 100 − 30 = 70.
+- For compatibility reasons, serialized color values are expressed as [`rgb()`](/en-US/docs/Web/CSS/color_value/rgb) colors if the alpha channel value is exactly `1`, and `rgba()` colors otherwise. In both cases, legacy syntax is used, with commas as separators (for example `rgb(255, 0, 0)`).
+
+The returned object is the same {{DOMxRef("CSSStyleDeclaration")}} type as the object returned from the element's {{DOMxRef("HTMLElement/style", "style")}} property. However, the two objects have different purposes:
+
+- The object from `getComputedStyle` is read-only, and should be used to inspect the element's style — including those set by a `<style>` element or an external stylesheet.
+- The `element.style` object should be used to **set** styles on that element, or inspect styles directly added to it from JavaScript manipulation or the global `style` attribute.
 
 ### Exceptions
 
@@ -52,17 +63,19 @@ object, which updates automatically when the element's styles are changed.
 
 ## Examples
 
+### Retrieving computed styles
+
 In this example we style a {{HTMLElement("p")}} element, then retrieve those styles
 using `getComputedStyle()`, and print them into the text content of the
 `<p>`.
 
-### HTML
+#### HTML
 
 ```html
 <p>Hello</p>
 ```
 
-### CSS
+#### CSS
 
 ```css
 p {
@@ -76,7 +89,7 @@ p {
 }
 ```
 
-### JavaScript
+#### JavaScript
 
 ```js
 const para = document.querySelector("p");
@@ -88,36 +101,11 @@ para.textContent =
   )}.`;
 ```
 
-### Result
-
-{{EmbedLiveSample('Examples', '100%', '240px')}}
+#### Result
 
-## Description
+{{EmbedLiveSample('retrieving_computed_styles', '100%', '240px')}}
 
-The returned object is the same {{DOMxRef("CSSStyleDeclaration")}} type as the object
-returned from the element's {{DOMxRef("HTMLElement/style", "style")}} property. However,
-the two objects have different purposes:
-
-- The object from `getComputedStyle` is read-only, and should be used to
-  inspect the element's style — including those set by a `<style>`
-  element or an external stylesheet.
-- The `element.style` object should be used to
-  **set** styles on that element, or inspect styles directly added to it
-  from JavaScript manipulation or the global `style` attribute.
-
-The first argument must be an {{domxref("Element")}}. Non-elements, like a
-{{DOMxRef("Text")}} node, will throw an error.
-
-## defaultView
-
-In many code samples, `getComputedStyle` is used from the
-{{DOMxRef("document.defaultView")}} object. In nearly all cases, this is needless, as
-`getComputedStyle` exists on the `window` object as well. It's
-likely the `defaultView` pattern was a combination of folks not wanting to
-write a testing spec for `window` and making an API that was also usable in
-Java.
-
-## Use with pseudo-elements
+### Use with pseudo-elements
 
 `getComputedStyle` can pull style info from pseudo-elements (such as
 `::after`, `::before`, `::marker`,
@@ -140,42 +128,6 @@ Java.
 </script>
 ```
 
-## Notes
-
-- The returned {{DOMxRef("CSSStyleDeclaration")}} object contains active values for
-  CSS property **_longhand_** names as well as shorthand names. For example, the returned object contains entries for
-  {{cssxref("border-bottom-width")}} in addition to the {{cssxref("border-width")}} and
-  {{cssxref("border")}} [shorthand property names](/en-US/docs/Web/CSS/CSS_cascade/Shorthand_properties). You can query values with longhand names like
-  {{cssxref("font-size")}} as well as shorthand names like {{cssxref("font")}}.
-- CSS property values may be accessed using the
-  {{DOMxRef("CSSStyleDeclaration.getPropertyValue", "getPropertyValue(propName)")}} method or by indexing directly into the object
-  using array or [dot notation](/en-US/docs/Learn_web_development/Core/Scripting/Object_basics#dot_notation) such as `obj['z-index']` or `obj.zIndex`.
-- The values returned by `getComputedStyle` are [resolved values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value).
-  These are usually the same as CSS 2.1's
-  [computed values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#computed_value), but for some older properties
-  like `width`, `height`, or `padding`, they are
-  instead the same as [used values](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#used_value). Originally, CSS
-  2.0 defined the _computed values_ as the "ready to be used" final values of
-  properties after cascading and inheritance, but CSS 2.1 redefined them as pre-layout,
-  and _used values_ as post-layout. For CSS 2.0 properties,
-  `getComputedStyle` returns the old meaning of computed values, now called
-  **used values**. An example difference between pre- and post-layout
-  values includes the resolution of percentages for `width` or
-  `height`, as those will be replaced by their pixel equivalent only for
-  _used values_.
-- Returned values are sometimes deliberately inaccurate. To avoid the "CSS History
-  Leak" security issue, browsers may lie about the computed styles for a visited link,
-  returning values as if the user never visited the linked URL. See [Plugging the CSS history leak](https://blog.mozilla.org/security/2010/03/31/plugging-the-css-history-leak/) and [Privacy-related changes coming to CSS `:visited`](https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/) for examples of how this is implemented.
-- During [CSS transitions](/en-US/docs/Web/CSS/CSS_transitions),
-  `getComputedStyle` returns the original property value in Firefox, but the
-  final property value in WebKit.
-- In Firefox, properties with the value `auto` return the used value, not
-  the value `auto`. So if you apply `top:auto` and
-  `bottom:0` on an element with `height:30px` and a containing
-  block of `height:100px`, Firefox's computed style for `top`
-  returns `70px`, as 100 − 30 = 70.
-- For compatibility reasons, serialized color values are expressed as [`rgb()`](/en-US/docs/Web/CSS/color_value/rgb) colors if the alpha channel value is exactly `1`, and `rgba()` colors otherwise. In both cases, legacy syntax is used, with commas as separators (for example `rgb(255, 0, 0)`).
-
 ## Specifications
 
 {{Specifications}}
@@ -188,4 +140,5 @@ Java.
 
 - {{DOMxRef("window.getDefaultComputedStyle()")}}
 - {{DOMxRef("CSSStyleDeclaration.getPropertyValue", "getPropertyValue()")}}
+- {{domxref("Element.computedStyleMap()")}}
 - [Resolved value](/en-US/docs/Web/CSS/CSS_cascade/Value_processing#resolved_value)