Merge branch 'main' into patch-2

mdn · May 14, 2024 · ba29b9d · ba29b9d
2 parents 2146126 + bc6e598
commit ba29b9d
Show file tree

Hide file tree

Showing 148 changed files with 2,113 additions and 957 deletions.
diff --git a/.lintstagedrc.js b/.lintstagedrc.js
@@ -0,0 +1,6 @@
+export default {
+ "files/en-us/_redirects.txt": (filenames) => [
+ `yarn content fix-redirects en-US`,
+ `yarn content validate-redirects en-us --strict`,
+ ],
+};
diff --git a/files/en-us/_redirects.txt b/files/en-us/_redirects.txt
@@ -3608,6 +3608,8 @@
 /en-US/docs/Glossary/SSL_Glossary /en-US/docs/Glossary/SSL
 /en-US/docs/Glossary/Scrollport /en-US/docs/Glossary/Scroll_container
 /en-US/docs/Glossary/Serialize /en-US/docs/Glossary/Serialization
+/en-US/docs/Glossary/Simple_header /en-US/docs/Glossary/CORS-safelisted_request_header
+/en-US/docs/Glossary/Simple_response_header /en-US/docs/Glossary/CORS-safelisted_response_header
 /en-US/docs/Glossary/Spartan /en-US/docs/Glossary/Microsoft_Edge
 /en-US/docs/Glossary/Static_property /en-US/docs/Glossary/property/JavaScript
 /en-US/docs/Glossary/Transferable_objects /en-US/docs/Web/API/Web_Workers_API/Transferable_objects

diff --git a/files/en-us/_wikihistory.json b/files/en-us/_wikihistory.json
@@ -4627,23 +4627,6 @@
  "modified": "2020-08-04T14:54:17.574Z",
  "contributors": ["jswisher", "hbloomer", "marumari", "fscholz"]
  },
- "Glossary/Simple_header": {
- "modified": "2019-07-06T03:48:05.558Z",
- "contributors": [
- "Annevk",
- "teoli",
- "fscholz",
- "hbloomer",
- "Andrew_Pfeiffer",
- "klez",
- "kscarfone",
- "chrisdavidmills"
- ]
- },
- "Glossary/Simple_response_header": {
- "modified": "2019-08-07T09:47:15.609Z",
- "contributors": ["fscholz", "SrihariThalla", "Sheppy", "teoli"]
- },
  "Glossary/Site": {
  "modified": "2020-03-27T15:47:42.365Z",
  "contributors": ["RafeyIqbalRahman", "lol768"]

diff --git a/files/en-us/glossary/cors-safelisted_request_header/index.md b/files/en-us/glossary/cors-safelisted_request_header/index.md
@@ -6,13 +6,13 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-A [**CORS-safelisted request header**](https://fetch.spec.whatwg.org/#cors-safelisted-request-header) is one of the following [HTTP headers](/en-US/docs/Web/HTTP/Headers):
+A [**CORS-safelisted request header**](https://fetch.spec.whatwg.org/#cors-safelisted-request-header) (also known as "simple header") is one of the following [HTTP headers](/en-US/docs/Web/HTTP/Headers):
 
-- {{HTTPHeader("Accept")}},
-- {{HTTPHeader("Accept-Language")}},
-- {{HTTPHeader("Content-Language")}},
-- {{HTTPHeader("Content-Type")}},
-- {{HTTPHeader("Range")}}.
+- {{HTTPHeader("Accept")}}
+- {{HTTPHeader("Accept-Language")}}
+- {{HTTPHeader("Content-Language")}}
+- {{HTTPHeader("Content-Type")}}
+- {{HTTPHeader("Range")}}
 
 When containing only these headers (and values that meet the additional requirements laid out below), a request doesn't need to send a {{glossary("preflight request")}} in the context of [CORS](/en-US/docs/Glossary/CORS).
 

diff --git a/files/en-us/glossary/cors-safelisted_response_header/index.md b/files/en-us/glossary/cors-safelisted_response_header/index.md
@@ -6,7 +6,7 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-A **CORS-safelisted response header** is an [HTTP header](/en-US/docs/Web/HTTP/Headers) in a [CORS](/en-US/docs/Web/HTTP/CORS) response that it is considered _safe_ to expose to client scripts. Only safelisted response headers are made available to web pages.
+A **CORS-safelisted response header** (also known as "simple response header") is an [HTTP header](/en-US/docs/Web/HTTP/Headers) in a [CORS](/en-US/docs/Web/HTTP/CORS) response that it is considered _safe_ to expose to client scripts. Only safelisted response headers are made available to web pages.
 
 By default, the safelist includes the following response headers:
 

diff --git a/files/en-us/glossary/decryption/index.md b/files/en-us/glossary/decryption/index.md
@@ -6,17 +6,16 @@ page-type: glossary-definition
 
 {{GlossarySidebar}}
 
-In {{glossary("cryptography")}}, **decryption** is the conversion of {{glossary("ciphertext")}} into {{glossary("Plaintext")}}.
+In {{glossary("cryptography")}}, **decryption** is the conversion of {{glossary("ciphertext")}} into {{glossary("plaintext")}}.
 
-Decryption is a cryptographic primitive: it transforms a ciphertext message into plaintext using a cryptographic algorithm called a {{glossary("cipher")}}. Like encryption, decryption in modern ciphers is performed using a specific algorithm and a secret, called the {{glossary("key")}}. Since the algorithm is often public, the key must stay secret if the encryption stays secure.
+Decryption is an operation which transforms a ciphertext message into plaintext using a cryptographic algorithm called a {{glossary("cipher")}}. Like encryption, decryption in modern ciphers is performed by using a specific algorithm and a secret, called the {{glossary("key")}}.
 
 ![The decryption primitive.](decryption.png)
 
-Decryption is the reverse of {{glossary("encryption")}} and if the key stays secret, decryption without knowing the specific secret, decryption is mathematically hard to perform. How hard depends on the security of the cryptographic algorithm chosen and evolves with the progress of {{glossary("cryptanalysis")}}.
+Decryption is the reverse process of {{glossary("encryption")}} and if the key stays secret, is mathematically hard to perform. How hard it is depends on how secure the cryptographic algorithm is, and that in itself is subject to change as the study of {{glossary("cryptanalysis")}} advances.
 
 ## See also
 
-- [Encryption and Decryption](/en-US/docs/Encryption_and_Decryption)
 - {{glossary("Encryption")}}
 - {{glossary("Cipher")}}
 - {{glossary("Cryptography")}}
diff --git a/files/en-us/glossary/simple_header/index.md b/files/en-us/glossary/simple_header/index.md
diff --git a/files/en-us/glossary/simple_response_header/index.md b/files/en-us/glossary/simple_response_header/index.md
diff --git a/files/en-us/learn/javascript/asynchronous/promises/index.md b/files/en-us/learn/javascript/asynchronous/promises/index.md
@@ -355,24 +355,28 @@ Instead, you'd need to do something like:
 
 ```js
 async function fetchProducts() {
- try {
- const response = await fetch(
- "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",
- );
- if (!response.ok) {
- throw new Error(`HTTP error: ${response.status}`);
- }
- const data = await response.json();
- return data;
- } catch (error) {
- console.error(`Could not get products: ${error}`);
+ const response = await fetch(
+ "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",
+ );
+ if (!response.ok) {
+ throw new Error(`HTTP error: ${response.status}`);
  }
+ const data = await response.json();
+ return data;
 }
 
 const promise = fetchProducts();
-promise.then((data) => console.log(data[0].name));
+promise
+ .then((data) => {
+ console.log(data[0].name);
+ })
+ .catch(() => {
+ console.error(`Could not get products: ${error}`);
+ });
 ```
 
+Here, we moved the `try...catch` back to the `catch` handler on the returned promise. This means our `then` handler doesn't have to deal with the case where an error got caught inside the `fetchProducts` function, causing `data` to be `undefined`. Handle errors as the last step of your promise chain.
+
 Also, note that you can only use `await` inside an `async` function, unless your code is in a [JavaScript module](/en-US/docs/Web/JavaScript/Guide/Modules). That means you can't do this in a normal script:
 
 ```js
@@ -388,6 +392,7 @@ try {
  console.log(data[0].name);
 } catch (error) {
  console.error(`Could not get products: ${error}`);
+ throw error;
 }
 ```
 

diff --git a/files/en-us/learn/performance/multimedia/index.md b/files/en-us/learn/performance/multimedia/index.md
@@ -126,6 +126,8 @@ Browsers begin rendering content as HTML is parsed, often before all assets, inc
 
 Without the `width` and `height` attributes, no placeholder space is created, creating a noticeable {{glossary('jank')}}, or layout shift, in the page when the image loads after the page is rendered. Page reflow and repaints are performance and usability issues.
 
+The [Cumulative Layout Shift (CLS)](https://web.dev/articles/cls) metric measures jank on page load, or how much visible content shifts in the viewport and by how much. The main culprits of bad CLS are replaced elements without declared dimensions that reflow when the asset loads, including images, ad, embeds, and iframes without an size or {{cssxref("aspect-ratio")}} and web fonts.
+
 In responsive designs, when a container is narrower than an image, the following CSS is generally used to keep images from breaking out of their containers:
 
 ```css
@@ -135,13 +137,13 @@ img {
 }
 ```
 
-While useful for responsive layouts, this causes jank when width and height information are not included, as if no height information is present when the `<img>` element is parsed but before the image has loaded, this CSS effectively has set the height to 0. When the image loads after the page has been initially rendered to the screen, the page reflows and repaints creating a layout shift as it creates space for the newly determined height.
+While useful for responsive layouts, this causes jank and poor CLS when width and height information are not included, as if no height information is present when the `<img>` element is parsed but before the image has loaded, this CSS effectively has set the height to 0. When the image loads after the page has been initially rendered to the screen, the page reflows and repaints creating a layout shift as it creates space for the newly determined height.
 
 Browsers have a mechanism for sizing images before the actual image is loaded. When an `<img>`, `<video>`, or `<input type="button">` element has `width` and `height` attributes set on it, its aspect ratio is calculated before load time, and is available to the browser, using the dimensions provided.
 
-The aspect ratio is then used to calculate the height and therefore the correct size is applied to the `<img>` element, meaning that the aforementioned jank will not occur, or be minimal if the listed dimensions are not fully accurate, when the image loads.
+The aspect ratio is then used to calculate the height, and therefore, the correct size is applied to the `<img>` element, meaning that the aforementioned jank will not occur or be minimal if the listed dimensions are not fully accurate when the image loads.
 
-The aspect ratio is used to reserve space only on the image load. Once the image has loaded, the intrinsic aspect ratio of the loaded image, rather than the aspect ratio from the attributes, is used. This ensures that it displays at the correct aspect ratio even if the attribute dimensions are not accurate.
+The aspect ratio is used to reserve space only on the image load. Once the image has loaded, the intrinsic aspect ratio of the loaded image or the value of the `aspect-ratio` property is used rather than the aspect ratio from the attributes. This ensures that it displays at the correct aspect ratio even if the attribute dimensions are not accurate.
 
 While developer best practices from the last decade may have recommended omitting the `width` and `height` attributes of an image on an HTML {{htmlelement("img")}}, due to aspect ratio mapping, including these two attributes is considered a developer best practice.
 

diff --git a/...es/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md b/...es/howto/write_an_api_reference/information_contained_in_a_webidl_file/index.md
@@ -17,7 +17,7 @@ WebIDL can be found in multiple locations:
 - Each specification contains WebIDL inside the text: it is a very convenient way to convey precise definition. These describe the syntax of the API. Though the canonical reference, we have to keep in mind that they may differ from the actual implementation. On MDN we want to be practical and document what the Web platform really is, not what it ideally should be. So double check what is there with implementations (and don't hesitate to file bugs if you discover incoherence).
 - Three browser engines use (modified) WebIDL as part as their toolchain: Gecko, Chromium/Blink, and WebCore/WebKit. Pre-Chromium versions of Edge used it internally, but these are unfortunately not public.
 
- - For Gecko, all WebIDL files are grouped in a single directory: <https://dxr.mozilla.org/mozilla-central/source/dom/webidl/>. Their extension is `.webidl`. There are other `*.idl` files in the Gecko source tree but they are not WebIDL, so you can ignore them. Older versions of Gecko have some of their WebIDL scattered around somewhat, and may even use Mozilla's IDL instead of WebIDL to describe some Web interfaces, but this won't be a problem in any recent Gecko code.
+ - For Gecko, all WebIDL files are grouped in a single directory: <https://searchfox.org/mozilla-central/source/dom/webidl/>. Their extension is `.webidl`. There are other `*.idl` files in the Gecko source tree but they are not WebIDL, so you can ignore them. Older versions of Gecko have some of their WebIDL scattered around somewhat, and may even use Mozilla's IDL instead of WebIDL to describe some Web interfaces, but this won't be a problem in any recent Gecko code.
  - For Chromium, they are located in two locations, both subtrees of the source code's [`renderer/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/) directory: [`core/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/core/) and [`modules/`](https://source.chromium.org/chromium/chromium/src/+/master:third_party/blink/renderer/modules/). Chromium source code has IDL files in other locations, but these are part of the testing system and not relevant to API implementations.
  - For WebCore, they are scattered around the source code, so you need to dig a bit more: E.g. <https://github.com/WebKit/webkit/blob/main/Source/WebCore/html/DOMTokenList.idl>
 

diff --git a/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md b/files/en-us/mozilla/add-ons/webextensions/user_interface/browser_styles/index.md
@@ -121,7 +121,7 @@ As `browser_style` is a deprecated in Manifest V3 you may want to remove support
 - Does the appearance of your extensions UI change?
  - If the appearance doesn't change, remove the key.
  - If the appearance changes, experiment to determine what dependency exist and add the relevant properties in the extension's stylesheet. The styles are most likely to cause layout changes are `box-sizing:`, `border-box`, and `display: flex`.
- If you cannot identify the dependencies, include the content of [extension.css](https://hg.mozilla.org/mozilla-central/raw-file/a445f1762c895000bcdabd9d95697522359d41ed/browser/components/extensions/extension.css) with the extension and delete all parts that aren't relevant, usually the `body` and `body *` blocks as most extensions don't use the `browser-style` class.
+ If you cannot identify the dependencies, include the content of [extension.css](https://searchfox.org/mozilla-central/source/browser/components/extensions/extension.css) with the extension and delete all parts that aren't relevant, usually the `body` and `body *` blocks as most extensions don't use the `browser-style` class.
 
 ## Firefox panel components (legacy)