Add `deprecate()` mixin (#28092)

diff --git a/scss/_mixins.scss b/scss/_mixins.scss
index 8710166660c0e21ebd0ed390187052501f74a917..254986cdeac52761091f0772b081f232b7eb1931 100644 (file)
--- a/scss/_mixins.scss
+++ b/scss/_mixins.scss
@@ -2,6 +2,9 @@
 //
 // Used in conjunction with global variables to enable certain theme features.
 
+// Deprecate
+@import "mixins/deprecate";
+
 // Utilities
 @import "mixins/breakpoints";
 @import "mixins/hover";

diff --git a/scss/_variables.scss b/scss/_variables.scss
index c916257e7818fe597b9a755d883f9da5db33bef6..bbd92a91aa011290bbcf605fc07d28d97507ad45 100644 (file)
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -117,6 +117,7 @@ $enable-grid-classes:                         true !default;
 $enable-pointer-cursor-for-buttons:           true !default;
 $enable-print-styles:                         true !default;
 $enable-validation-icons:                     true !default;
+$enable-deprecation-messages:                 true !default;
 
 
 // Spacing

diff --git a/scss/mixins/_deprecate.scss b/scss/mixins/_deprecate.scss
new file mode 100644 (file)
index 0000000..43d6f1e
--- /dev/null
+++ b/scss/mixins/_deprecate.scss
@@ -0,0 +1,10 @@
+// Deprecate mixin
+//
+// This mixin can be used to deprecate mixins or functions.
+// `$enable-deprecation-messages` is a global variable, `$ignore-warning` is a variable that can be passed to
+// some deprecated mixins to suppress the warning (for example if the mixin is still be used in the current version of Bootstrap)
+@mixin deprecate($name, $deprecate-version, $remove-version, $ignore-warning) {
+  @if ($enable-deprecation-messages != false and $ignore-warning != true) {
+    @warn "#{$name} has been deprecated as of #{$deprecate-version}. It will be removed entirely in #{$remove-version}.";
+  }
+}

diff --git a/scss/mixins/_text-hide.scss b/scss/mixins/_text-hide.scss
index 9ffab169f3b3671b128efe6be4ab6dac3e9c581b..3a923011ec73de336b6d89f731b0a81dcc14c4a7 100644 (file)
--- a/scss/mixins/_text-hide.scss
+++ b/scss/mixins/_text-hide.scss
@@ -7,7 +7,5 @@
   background-color: transparent;
   border: 0;
 
-  @if ($ignore-warning != true) {
-    @warn "The `text-hide()` mixin has been deprecated as of v4.1.0. It will be removed entirely in v5.";
-  }
+  @include deprecate("`text-hide()`", "v4.1.0", "v5", $ignore-warning);
 }

diff --git a/site/docs/4.2/getting-started/theming.md b/site/docs/4.2/getting-started/theming.md
index db3b12ffd4218008e5cff1339c66ff39ef2b7eea..a40b6395ac05c05ceb711db6565f6574835c42a4 100644 (file)
--- a/site/docs/4.2/getting-started/theming.md
+++ b/site/docs/4.2/getting-started/theming.md
@@ -243,6 +243,7 @@ You can find and customize these variables for key global options in Bootstrap's
 | `$enable-pointer-cursor-for-buttons`         | `true` (default) or `false`        | Add "hand" cursor to non-disabled button elements. |
 | `$enable-print-styles`                       | `true` (default) or `false`        | Enables styles for optimizing printing. |
 | `$enable-validation-icons`                   | `true` (default) or `false`        | Enables `background-image` icons within textual inputs and some custom forms for validation states. |
+| `$enable-deprecation-messages`               | `true` or `false` (default)        | Set to `true` to show warnings when using any of the deprecated mixins and functions that are planned to be removed in `v5`. |
 
 ## Color