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

diff --git a/docs/4.0/getting-started/browsers-devices.md b/docs/4.0/getting-started/browsers-devices.md
index 1635579c4755361eab8d65e103e6035e68efdb75..63ee7c30edf9f2160cf2ba528f841eb51c6e004b 100644 (file)
--- a/docs/4.0/getting-started/browsers-devices.md
+++ b/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
 

diff --git a/docs/4.0/getting-started/theming.md b/docs/4.0/getting-started/theming.md
index 8ef8bb29450abee04892e9aa72d829d1e81b1bdd..f8e9bf6f2665af4c4cffc28a3f1b49c792961942 100644 (file)
--- a/docs/4.0/getting-started/theming.md
+++ b/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
 

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 31149a5e496c404a0db81d60103b8208eed7a978..3e47a1d1e9958c474e5600ec0ed112ce6dc4dff8 100644 (file)
--- a/scss/_variables.scss
+++ b/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;
 

diff --git a/scss/mixins/_hover.scss b/scss/mixins/_hover.scss
index fd2f1e2cdae019d2f16bbdb56f6351e64d9ab09c..ec2e328a4c201272c7c0e6a3c11c2cf3b4b6e503 100644 (file)
--- a/scss/mixins/_hover.scss
+++ b/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;
   }
 }