[pull] main from mdn:main

.github/workflows/pr-review-companion.yml

@@ -33,7 +33,7 @@ jobs:
     if: github.event.workflow_run.conclusion == 'success'
     steps:
       - name: "Download artifact"
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           pattern: build
           path: build

files/en-us/web/css/caret-color/index.md

@@ -6,7 +6,7 @@ browser-compat: css.properties.caret-color
 sidebar: cssref
 ---
 
-The **`caret-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of the **insertion caret**, the visible marker where the next character typed will be inserted. This is sometimes referred to as the **text input cursor**. The caret appears in elements such as {{HTMLElement("input")}} or those with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute. The caret is typically a thin vertical line that flashes to help make it more noticeable. By default, it is black, but its color can be altered with this property.
+The **`caret-color`** [CSS](/en-US/docs/Web/CSS) property sets the color of the **insertion caret**, sometimes referred to as the **text input cursor**. This is the visible marker appearing at the insertion point where the next character typed will be added or where the next character deleted will be removed.
 
 {{InteractiveExample("CSS Demo: caret-color")}}
 
@@ -37,8 +37,6 @@ caret-color: transparent;
 }
 ```
 
-Note that the insertion caret is only one type of caret. For example, many browsers have a "navigation caret," which acts similarly to an insertion caret but can be moved around in non-editable text. On the other hand, the mouse cursor image shown when hovering over text where the {{cssxref("cursor")}} property is `auto`, or when hovering over an element where the `cursor` property is `text` or `vertical-text`, though it sometimes looks like a caret, is not a caret (it's a cursor).
-
 ## Syntax
 
 ```css
@@ -64,14 +62,37 @@ caret-color: unset;
 ### Values
 
 - `auto`
-  - : The user agent selects an appropriate color for the caret. This is generally {{cssxref("<color>","currentColor","#currentcolor_keyword")}}, but the user agent may choose a different color to ensure good visibility and contrast with the surrounding content, taking into account the value of `currentColor`, the background, shadows, and other factors.
-
-    > [!NOTE]
-    > While user agents may use `currentColor` (which is usually animatable) for the `auto` value, `auto` is not interpolated in transitions and animations.
+  - : Generally resolves to [`currentColor`](/en-US/docs/Web/CSS/color_value#currentcolor_keyword), the {{cssxref("color")}} of the text that will be modified.
 
 - {{cssxref("<color>")}}
   - : The color of the caret.
 
+## Description
+
+An insertion caret is a visible indicator of the spot within editable text — or within an element that accepts text input — where content will be inserted (or deleted) by the user. The caret is typically a thin vertical line indicating where the addition or deletion of characters will occur. It generally blinks (flashes on and off), so it is more noticeable. The caret only appears when the editable element has focus. By default, this caret is the color of the text. The `caret-color` property can be used to set the color of this caret to something other than the `currentColor`, or to reset a colored caret back to its default.
+
+The `auto` value sets the insertion caret to `currentColor`, which is the {{cssxref("color")}} of the text that is being added or deleted. User agents may choose a different color to ensure good visibility and contrast with the surrounding content, taking into account the {{cssxref("color")}}, {{cssxref("background-color")}}, shadows, and other factors. In practice, however, all browsers use the current color by default, and when `caret-color` is set to `auto`. You can set any valid `<color>` as the value.
+
+### Understanding insertion carets
+
+The insertion caret, and therefore this property, only applies to text or elements that can accept text input. The caret appears in focused user interface elements where users can update content, such as {{HTMLElement("input")}} elements that accept freeform text, the {{HTMLElement("textarea")}} element, and elements with the [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute set.
+
+The caret may appear in `<input>` elements of type `password`, `text`, `search`, `tel`, and `email`. No caret exists with date, `color`, `hidden`, `radio`, or `checkbox` input types. Some browsers display a caret with the `number` input type. It is possible in some browsers to make a caret appear in elements that never have text content — for example, by setting [`appearance: none`](/en-US/docs/Web/CSS/appearance) and adding the `contenteditable` attribute. However, this is not recommended.
+
+A caret may be displayed in an editable element or its descendants, provided the editability is not disabled, for example by setting a descendant element's `contentEditable` attribute to `false`. If an element is not editable or selectable, for example if {{cssxref("user-select")}} is set to `none`, the caret should not appear.
+
+### Caret versus cursor
+
+There are multiple types of carets. The insertion caret is the only type affected by the `caret-color` property.
+
+Many browsers have a **navigation caret**, which acts similarly to an insertion caret but can be moved around in non-editable text.
+
+The mouse cursor image shown for certain {{cssxref("cursor")}} property values (for example, `auto` or `text`) may resemble a caret, but it's not. It's a cursor.
+
+### Animating from `auto`
+
+Generally, when the `caret-color` is set to or defaults to `auto`, user agents use `currentColor`, which is animatable. However, `auto` is not an animatable value by default: when animating or transitioning the `caret-color` from `auto` to any color value, no interpolation happens. The animation is [discrete](/en-US/docs/Web/CSS/CSS_animated_properties#discrete); the color switches from or to the `currentColor` color at the midpoint of the {{cssxref("animation-duration")}} or {{cssxref("transition-duration")}}.
+
 ## Formal definition
 
 {{cssinfo}}
@@ -104,7 +125,7 @@ input {
 }
 
 input.custom {
-  caret-color: red;
+  caret-color: orange;
 }
 
 p.custom {
@@ -126,7 +147,10 @@ p.custom {
 
 ## See also
 
-- The {{HTMLElement("input")}} element
-- The HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute, which can be used to make any element's text editable
-- The {{cssxref("&lt;color&gt;")}} data type
-- Other color-related properties: {{cssxref("color")}}, {{cssxref("background-color")}}, {{cssxref("border-color")}}, {{cssxref("outline-color")}}, {{cssxref("text-decoration-color")}}, {{cssxref("text-emphasis-color")}}, {{cssxref("text-shadow")}}, and {{cssxref("column-rule-color")}}
+- {{cssxref("color")}}
+- {{cssxref("text-emphasis")}}
+- {{cssxref("cursor")}}
+- {{cssxref("text-emphasis")}}
+- CSS {{cssxref("&lt;color&gt;")}} data type
+- {{HTMLElement("input")}} element
+- HTML [`contenteditable`](/en-US/docs/Web/HTML/Reference/Global_attributes/contenteditable) attribute

files/en-us/web/css/css_basic_user_interface/index.md

@@ -95,7 +95,7 @@ Click "Play" in the example above to see or edit the code for the animation in t
 - {{CSSxRef("resize")}}
 - {{CSSxRef("user-select")}}
 
-The CSS basic user interface module also defines the `caret`, `caret-shape`, `nav-down`, `nav-left`, `nav-right`, and `nav-up` properties. Currently, no browsers support these features.
+The CSS basic user interface module also defines the `caret`, `caret-animation`, `caret-shape`, `nav-down`, `nav-left`, `nav-right`, and `nav-up` properties. Currently, no browsers support these features.
 
 ## Guides
 

files/en-us/web/css/css_text_decoration/text_shadows/index.md

@@ -1,5 +1,6 @@
 ---
 title: Introduction to text shadows
+short-title: Text shadows
 slug: Web/CSS/CSS_text_decoration/Text_shadows
 page-type: guide
 sidebar: cssref

files/en-us/web/javascript/guide/closures/index.md

@@ -492,28 +492,20 @@ setupHelp();
 
 This example uses `const` instead of `var`, so every closure binds the block-scoped variable, meaning that no additional closures are required.
 
-Another alternative could be to use `forEach()` to iterate over the `helpText` array and attach a listener to each [`<input>`](/en-US/docs/Web/HTML/Reference/Elements/input), as shown:
+If you are writing modern JavaScript anyway, you can consider more alternatives to the plain `for` loop, such as using {{jsxref("Statements/for...of", "for...of")}} loop and declaring `item` as `let` or `const`, or using the {{jsxref("Array/forEach", "forEach()")}} method, which both avoid the closure problem.
 
 ```js
-function showHelp(help) {
-  document.getElementById("help").textContent = help;
-}
-
-function setupHelp() {
-  var helpText = [
-    { id: "email", help: "Your email address" },
-    { id: "name", help: "Your full name" },
-    { id: "age", help: "Your age (you must be over 16)" },
-  ];
-
-  helpText.forEach(function (text) {
-    document.getElementById(text.id).onfocus = function () {
-      showHelp(text.help);
-    };
-  });
+for (const item of helpText) {
+  document.getElementById(item.id).onfocus = () => {
+    document.getElementById("help").textContent = item.help;
+  };
 }
 
-setupHelp();
+helpText.forEach((item) => {
+  document.getElementById(item.id).onfocus = () => {
+    showHelp(item.help);
+  };
+});
 ```
 
 ## Performance considerations

files/sidebars/cssref.yaml

@@ -313,6 +313,10 @@ sidebar:
     details: closed
     children:
       - /Web/CSS/CSS_text/Wrapping_breaking_text
+  - title: Text decoration
+    details: closed
+    children:
+      - /Web/CSS/CSS_text_decoration/Text_shadows
   - title: Transforms
     details: closed
     children: