Deprecate hover media query shim and mixins (#25270)

* Deprecate hover media query shim and mixins

Fixes #25195.

This never was completed or fully implemented, and the docs are inaccurate as to what browsers are currently affected by this stickied hover problem. This PR aims to update the docs and deprecate the shim from our mixins and only return the pseudo-classes. To reflect the order of these states used elsewhere (e.g., our button styles), I've also updated the order of each within the mixin.

* Mention in docs and variables that it's deprecated

docs/4.0/getting-started/browsers-devices.md

@@ -123,11 +123,11 @@ The `.dropdown-backdrop` element isn't used on iOS in the nav because of the com
 
 Page zooming inevitably presents rendering artifacts in some components, both in Bootstrap and the rest of the web. Depending on the issue, we may be able to fix it (search first and then open an issue if need be). However, we tend to ignore these as they often have no direct solution other than hacky workarounds.
 
-## Sticky `:hover`/`:focus` on mobile
+## Sticky `:hover`/`:focus` on iOS
 
-Even though real hovering isn't possible on most touchscreens, most mobile browsers emulate hovering support and make `:hover` "sticky". In other words, `:hover` styles start applying after tapping an element and only stop applying after the user taps some other element. On mobile-first sites, this behavior is normally undesirable.
+While `:hover` isn't possible on most touch devices, iOS emulates this behavior, resulting in "sticky" hover styles that persist after tapping one element. These hover styles are only removed when users tap another element. This behavior is considered largely undesirable and appears to not be an issue on Android or Windows devices.
 
-Bootstrap includes a workaround for this, although it is disabled by default. By setting `$enable-hover-media-query` to `true` when compiling from Sass, Bootstrap will use [mq4-hover-shim](https://github.com/twbs/mq4-hover-shim) to disable `:hover` styles in browsers that emulate hovering, thus preventing sticky `:hover` styles. There are some caveats to this workaround; see the shim's documentation for details.
+Throughout our v4 alpha and beta releases, we included incomplete and commented out code for opting into a media query shim that would disable hover styles in touch device browsers that emulate hovering. This work was never fully completed or enabled, but to avoid complete breakage, we've opted to deprecate [this shim](https://github.com/twbs/mq4-hover-shim) and keep the mixins as shortcuts for the pseudo-classes.
 
 ## Printing
 

docs/4.0/getting-started/theming.md

@@ -206,14 +206,14 @@ You can find and customize these variables for key global options in our `_varia
 | Variable                    | Values                             | Description                                                                            |
 | --------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------- |
 | `$spacer`                   | `1rem` (default), or any value > 0 | Specifies the default spacer value to programmatically generate our [spacer utilities]({{ site.baseurl }}/docs/{{ site.docs_version }}/utilities/spacing/). |
-| `$enable-rounded`           | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components.                       |
-| `$enable-shadows`           | `true` or `false` (default)        | Enables predefined `box-shadow` styles on various components.                          |
-| `$enable-gradients`         | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components.      |
-| `$enable-transitions`       | `true` (default) or `false`        | Enables predefined `transition`s on various components.                                |
-| `$enable-hover-media-query` | `true` or `false` (default)        | ...                                                                                    |
-| `$enable-grid-classes`      | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g., `.container`, `.row`, `.col-md-1`, etc.).     |
-| `$enable-caret`             | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`.                                    |
-| `$enable-print-styles`      | `true` (default) or `false`        | Enables styles for optimizing printing.                                |
+| `$enable-rounded`           | `true` (default) or `false`        | Enables predefined `border-radius` styles on various components. |
+| `$enable-shadows`           | `true` or `false` (default)        | Enables predefined `box-shadow` styles on various components. |
+| `$enable-gradients`         | `true` or `false` (default)        | Enables predefined gradients via `background-image` styles on various components. |
+| `$enable-transitions`       | `true` (default) or `false`        | Enables predefined `transition`s on various components. |
+| `$enable-hover-media-query` | `true` or `false` (default)        | **Deprecated** |
+| `$enable-grid-classes`      | `true` (default) or `false`        | Enables the generation of CSS classes for the grid system (e.g., `.container`, `.row`, `.col-md-1`, etc.). |
+| `$enable-caret`             | `true` (default) or `false`        | Enables pseudo element caret on `.dropdown-toggle`. |
+| `$enable-print-styles`      | `true` (default) or `false`        | Enables styles for optimizing printing. |
 
 ## Color
 

scss/_variables.scss

@@ -103,7 +103,7 @@ $enable-rounded:            true !default;
 $enable-shadows:            false !default;
 $enable-gradients:          false !default;
 $enable-transitions:        true !default;
-$enable-hover-media-query:  false !default;
+$enable-hover-media-query:  false !default; // Deprecated, no longer affects any compiled CSS
 $enable-grid-classes:       true !default;
 $enable-print-styles:       true !default;
 

scss/mixins/_hover.scss

@@ -1,61 +1,39 @@
 // stylelint-disable indentation
+
+// Hover mixin and `$enable-hover-media-query` are deprecated.
+//
+// Origally added during our alphas and maintained during betas, this mixin was
+// designed to prevent `:hover` stickiness on iOS—an issue where hover styles
+// would persist after initial touch.
+//
+// For backward compatibility, we've kept these mixins and updated them to
+// always return their regular psuedo-classes instead of a shimmed media query.
+//
+// Issue: https://github.com/twbs/bootstrap/issues/25195
+
 @mixin hover {
-  // TODO: re-enable along with mq4-hover-shim
-//  @if $enable-hover-media-query {
-//    // See Media Queries Level 4: https://drafts.csswg.org/mediaqueries/#hover
-//    // Currently shimmed by https://github.com/twbs/mq4-hover-shim
-//    @media (hover: hover) {
-//      &:hover { @content }
-//    }
-//  }
-//  @else {
-    &:hover { @content; }
-//  }
+  &:hover { @content; }
 }
 
-
 @mixin hover-focus {
-  @if $enable-hover-media-query {
-    &:focus {
-      @content;
-    }
-    @include hover { @content; }
-  } @else {
-    &:focus,
-    &:hover {
-      @content;
-    }
+  &:hover,
+  &:focus {
+    @content;
   }
 }
 
 @mixin plain-hover-focus {
-  @if $enable-hover-media-query {
-    &,
-    &:focus {
-      @content;
-    }
-    @include hover { @content; }
-  } @else {
-    &,
-    &:focus,
-    &:hover {
-      @content;
-    }
+  &,
+  &:hover,
+  &:focus {
+    @content;
   }
 }
 
 @mixin hover-focus-active {
-  @if $enable-hover-media-query {
-    &:focus,
-    &:active {
-      @content;
-    }
-    @include hover { @content; }
-  } @else {
-    &:focus,
-    &:active,
-    &:hover {
-      @content;
-    }
+  &:hover,
+  &:focus,
+  &:active {
+    @content;
   }
 }