docs: add Sass modules support documentation

Author: mrholek

docs/content/customize/color-modes.md

@@ -195,6 +195,46 @@ Adding a new color in `$theme-colors` is not enough for some of our components l
 
 This is a manual process because Sass cannot generate its own Sass variables from an existing variable or map. In future versions of Bootstrap, we'll revisit this setup to reduce the duplication.
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+// Required
+@use "sass:map";
+@use "variables" as *;
+@use "maps" as *;
+
+// Add a custom color to $theme-colors
+$custom-colors: (
+  "custom-color": #712cf9
+);
+$theme-colors: map.merge($theme-colors, $custom-colors);
+// Add a custom color to new theme maps
+
+// Light mode
+$custom-colors-text: ("custom-color": #712cf9);
+$custom-colors-bg-subtle: ("custom-color": #e1d2fe);
+$custom-colors-border-subtle: ("custom-color": #bfa1fc);
+
+$theme-colors-text: map.merge($theme-colors-text, $custom-colors-text);
+$theme-colors-bg-subtle: map.merge($theme-colors-bg-subtle, $custom-colors-bg-subtle);
+$theme-colors-border-subtle: map.merge($theme-colors-border-subtle, $custom-colors-border-subtle);
+
+// Dark mode
+$custom-colors-text-dark: ("custom-color": #e1d2f2);
+$custom-colors-bg-subtle-dark: ("custom-color": #8951fa);
+$custom-colors-border-subtle-dark: ("custom-color": #e1d2f2);
+
+$theme-colors-text-dark: map.merge($theme-colors-text-dark, $custom-colors-text-dark);
+$theme-colors-bg-subtle-dark: map.merge($theme-colors-bg-subtle-dark, $custom-colors-bg-subtle-dark);
+$theme-colors-border-subtle-dark: map.merge($theme-colors-border-subtle-dark, $custom-colors-border-subtle-dark);
+
+// Import CoreUI
+@use "coreui";
+
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 // Required
 @import "functions";
@@ -231,7 +271,7 @@ $theme-colors-text-dark: map-merge($theme-colors-text-dark, $custom-colors-text-
 $theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, $custom-colors-bg-subtle-dark);
 $theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, $custom-colors-border-subtle-dark);
 
-// Remainder of Bootstrap imports
+// Remainder of CoreUI for Bootstrap imports
 @import "root";
 @import "reboot";
 // etc

docs/content/customize/color.md

@@ -477,6 +477,38 @@ Bootstrap doesn't include `color` and `background-color` utilities for every col
 
 Here's an example that generates text color utilities (e.g., `.text-purple-500`) using the above steps.
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "sass:map";
+@use "@coreui/coreui/scss/functions/maps" as *;
+@use "@coreui/coreui/scss/variables" as *;
+@use "@coreui/coreui/scss/utilities" as *;
+
+$all-colors: map-merge-multiple($blues, $indigos, $purples, $pinks, $reds, $oranges, $yellows, $greens, $teals, $cyans);
+
+$utilities: map-merge(
+  $utilities,
+  (
+    "color": map-merge(
+      map-get($utilities, "color"),
+      (
+        values: map-merge(
+          map-get(map-get($utilities, "color"), "values"),
+          (
+            $all-colors
+          ),
+        ),
+      ),
+    ),
+  )
+);
+
+@use "@coreui/coreui/scss/utilities/api";
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 @import "@coreui/coreui/scss/functions";
 @import "@coreui/coreui/scss/variables";

docs/content/customize/sass.md

@@ -37,6 +37,41 @@ your-project/
 
 In your `custom.scss`, you'll import CoreUI's source Sass files. You have two options: include all of CoreUI, or pick the parts you need. We encourage the latter, though be aware there are some requirements and dependencies across our components. You also will need to include some JavaScript for our plugins.
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+// Custom.scss
+// Option A: Include all of CoreUI
+
+@use "@coreui/coreui/scss/coreui";
+
+// Then add additional custom code here
+```
+
+```scss
+// Custom.scss
+// Option B: Include parts of CoreUI
+
+// 1. Include 
+@use "@coreui/coreui/scss/root";
+
+// 2. Optionally include any other parts as needed
+@use "@coreui/coreui/scss/utilities";
+@use "@coreui/coreui/scss/reboot";
+@use "@coreui/coreui/scss/type";
+@use "@coreui/coreui/scss/images";
+@use "@coreui/coreui/scss/containers";
+@use "@coreui/coreui/scss/grid";
+@use "@coreui/coreui/scss/helpers";
+
+// 3. Optionally include utilities API last to generate classes based on the Sass map in `_utilities.scss`
+@use "@coreui/coreui/scss/utilities/api";
+
+// 4. Add additional custom code here
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 // Custom.scss
 // Option A: Include all of CoreUI
@@ -125,6 +160,17 @@ Variable overrides must come after our functions are imported, but before the re
 
 Here's an example that changes the `background-color` and `color` for the `<body>` when importing and compiling CoreUI for Bootstrap via npm:
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "@coreui/coreui/scss/coreui" with (
+  $body-bg: #000,
+  $body-color: #111
+)
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 // Required
 @import "../node_modules/@coreui/coreui/scss/functions";
@@ -175,6 +221,23 @@ $theme-colors: (
 
 Add new colors to `$theme-colors`, or any other map, by creating a new Sass map with your custom values and merging it with the original map. In this case, we'll create a new `$custom-colors` map and merge it with `$theme-colors`.
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "sass:map";
+@use "@coreui/coreui/scss/variables" as *;
+
+$custom-colors: (
+  "custom-color": #900
+);
+
+$theme-colors: map.merge($theme-colors, $custom-colors);
+
+@use "@coreui/coreui/scss/coreui";
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 // Create your own map
 $custom-colors: (
@@ -189,6 +252,21 @@ $theme-colors: map-merge($theme-colors, $custom-colors);
 
 To remove colors from `$theme-colors`, or any other map, use `map-remove`. Be aware you must insert it between our requirements and options:
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "sass:map";
+@use "@coreui/coreui/scss/variables" as *;
+@use "@coreui/coreui/scss/maps" as *;
+
+$theme-colors: map-remove($theme-colors, "info", "light", "dark");
+$theme-colors-border-subtle: map.remove($theme-colors-border-subtle, "info", "light", "dark");
+
+@use "@coreui/coreui/scss/coreui";
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 // Required
 @import "../node_modules/@coreui/coreui/scss/functions";
@@ -231,6 +309,8 @@ You can lighten or darken colors with CoreUI for Bootstrap's `tint-color()` and
 In practice, you'd call the function and pass in the color and weight parameters.
 
 ```scss
+@use "@coreui/coreui/scss/functions/color" as *;
+
 .custom-element {
   color: tint-color($primary, 10%);
 }
@@ -251,9 +331,14 @@ In order to meet the [Web Content Accessibility Guidelines (WCAG)](https://www.w
 
 An additional function we include in CoreUI for Bootstrap is the color contrast function, `color-contrast`. It utilizes the [WCAG 2.0 algorithm](https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) in a `sRGB` colorspace to automatically return a light (`#fff`), dark (`#212529`) or black (`#000`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
 
+{{< scss-docs name="color-contrast-function" file="scss/functions/_color-contrast.scss" >}}
+
 For example, to generate color swatches from our `$theme-colors` map:
 
+
 ```scss
+@use "@coreui/coreui/scss/functions/color-contrast" as *;
+
 @each $color, $value in $theme-colors {
   .swatch-#{$color} {
     color: color-contrast($value);
@@ -264,6 +349,8 @@ For example, to generate color swatches from our `$theme-colors` map:
 It can also be used for one-off contrast needs:
 
 ```scss
+@use "@coreui/coreui/scss/functions/color-contrast" as *;
+
 .custom-element {
   color: color-contrast(#000); // returns `color: #fff`
 }
@@ -272,6 +359,8 @@ It can also be used for one-off contrast needs:
 You can also specify a base color with our color map functions:
 
 ```scss
+@use "@coreui/coreui/scss/functions/color-contrast" as *;
+
 .custom-element {
   color: color-contrast($dark); // returns `color: #fff`
 }
@@ -288,6 +377,8 @@ We use the `add` and `subtract` functions to wrap the CSS `calc` function. The p
 Example where the calc is valid:
 
 ```scss
+@use "@coreui/coreui/scss/functions/math" as *;
+
 $border-radius: .25rem;
 $border-width: 1px;
 
@@ -305,6 +396,8 @@ $border-width: 1px;
 Example where the calc is invalid:
 
 ```scss
+@use "@coreui/coreui/scss/functions/math" as *;
+
 $border-radius: .25rem;
 $border-width: 0;
 
@@ -330,6 +423,8 @@ A shorthand mixin for the `prefers-color-scheme` media query is available with s
 {{< scss-docs name="mixin-color-scheme" file="scss/mixins/_color-scheme.scss" >}}
 
 ```scss
+@use "@coreui/coreui/scss/mixins/color-scheme" as *;
+
 .custom-element {
   @include color-scheme(light) {
     // Insert light mode styles here

docs/content/getting-started/parcel.md

@@ -112,8 +112,16 @@ Importing CoreUI into Parcel requires two imports, one into our `styles.scss` an
 
 1. **Import CoreUI's CSS.** Add the following to `src/scss/styles.scss` to import all of CoreUI's source Sass.
 
+   {{< callout-dart-sass-modules >}}
+   
    ```scss
    // Import all of CoreUI's CSS
+   @use "~@coreui/coreui/scss/coreui";
+   ```
+
+   {{< callout-dart-sass-deprecations >}}
+  
+   ```scss
    @import "~@coreui/coreui/scss/coreui";
    ```
 

docs/content/getting-started/rtl.md

@@ -105,9 +105,22 @@ $font-family-sans-serif:
 
 Need both LTR and RTL on the same page? All you have to do is set following variables:
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "@coreui/coreui/scss/coreui" with (
+  $enable-ltr: true,
+  $enable-rtl: true
+);
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 $enable-ltr: true;
 $enable-rtl: true;
+
+@import "../node_modules/@coreui/coreui/scss/coreui";
 ```
 
 
@@ -117,9 +130,22 @@ After running Sass, each selector in your CSS files will be prepended by `html:n
 
 By default LTR is enable and RTL is disable, but you can easily change it and use only RTL.
 
+{{< callout-dart-sass-modules >}}
+
+```scss
+@use "@coreui/coreui/scss/coreui" with (
+  $enable-ltr: false,
+  $enable-rtl: true
+);
+```
+
+{{< callout-dart-sass-deprecations >}}
+
 ```scss
 $enable-ltr: false;
 $enable-rtl: true;
+
+@import "../node_modules/@coreui/coreui/scss/coreui";
 ```
 
 ## Additional resources

docs/content/getting-started/vite.md

@@ -148,8 +148,16 @@ In the next and final section to this guide, we’ll import all of CoreUI’s CS
 
 2. **Now, let's import CoreUI's CSS.** Add the following to `src/scss/styles.scss` to import all of CoreUI's source Sass.
 
+  {{< callout-dart-sass-modules >}}
+
    ```scss
    // Import all of CoreUI's CSS
+   @use "~@coreui/coreui/scss/coreui";
+   ```
+
+   {{< callout-dart-sass-deprecations >}}
+  
+   ```scss
    @import "~@coreui/coreui/scss/coreui";
    ```
 

docs/content/getting-started/webpack.md

@@ -184,8 +184,16 @@ Importing CoreUI into Webpack requires the loaders we installed in the first sec
 
 2. **Now, let's import CoreUI's CSS.** Add the following to `src/scss/styles.scss` to import all of CoreUI's source Sass.
 
+  {{< callout-dart-sass-modules >}}
+
    ```scss
    // Import all of CoreUI's CSS
+   @use "~@coreui/coreui/scss/coreui";
+   ```
+
+   {{< callout-dart-sass-deprecations >}}
+  
+   ```scss
    @import "~@coreui/coreui/scss/coreui";
    ```
 

docs/layouts/shortcodes/callout-dart-sass-deprecations.html

@@ -0,0 +1,6 @@
+<div class="docs-callout docs-callout-warning">
+  <p>
+    <strong>Sass <code>@import</code> are deprecated and will be removed in Dart Sass 3.0.0.!</strong> 
+  </p>
+  <p>You can also use <code>@import</code> rules, but please be aware that they are deprecated and will be removed in Dart Sass 3.0.0, resulting in a compilation warning. You can learn more about this deprecation <a href="https://sass-lang.com/documentation/breaking-changes/import/" target="_blank">here</a>.</p>
+</div>

docs/layouts/shortcodes/callout-dart-sass-modules.html

@@ -0,0 +1,8 @@
+<div class="docs-callout docs-callout-info">
+  <p>
+    <strong>Heads up!</strong> Since <code>@coreui/coreui</code> v5.3.0 and <code>@coreui/coreui-pro</code> v5.10.0, we support Sass modules.
+  </p>
+  <p>
+    You can now use the modern <code>@use</code> and <code>@forward</code> rules instead of <code>@import</code>, which is deprecated and will be removed in Dart Sass 3.0.0. Using <code>@import</code> will result in a compilation warning. You can learn more about this transition <a href="https://sass-lang.com/documentation/breaking-changes/import/" target="_blank">here</a>.
+  </p>
+</div>

scss/functions/_color-contrast.scss

@@ -4,6 +4,7 @@
 // Color contrast
 // See https://github.com/twbs/bootstrap/pull/30168
 
+// scss-docs-start color-contrast-function
 @function color-contrast($background, $color-contrast-dark: $color-contrast-dark, $color-contrast-light: $color-contrast-light, $min-contrast-ratio: $min-contrast-ratio) {
   $foregrounds: $color-contrast-light, $color-contrast-dark, $white, $black;
   $max-ratio: 0;
@@ -23,3 +24,4 @@
 
   @return $max-ratio-color;
 }
+// scss-docs-end color-contrast-function