docs: update content

code · pull · Dec 29, 2024 · Dec 30, 2024 · Dec 31, 2024 · Jan 2, 2025
commit ef0e750557f4327b5b6f887ed36151f79dffd152
diff --git a/packages/docs/content/components/alert/index.mdx b/packages/docs/content/components/alert/index.mdx
@@ -13,12 +13,7 @@ React Alert is prepared for any length of text, as well as an optional close but
 
 <ExampleSnippet component="AlertExample" componentName="React Alert" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  Using color to add meaning only provides a visual indication, which will not be conveyed to
-  users of assistive technologies – such as screen readers. Ensure that information denoted by the
-  color is either obvious from the content itself (e.g. the visible text), or is included through
-  alternative means, such as additional text hidden with the `.visually-hidden` class.
-</Callout>
+<Callout color="warning" type="colorAssistiveTechnologies" />
 
 ### Live example
 

diff --git a/packages/docs/content/components/button-group/index.mdx b/packages/docs/content/components/button-group/index.mdx
@@ -12,10 +12,10 @@ Wrap a series of `<CButton>` components in `<CButtonGroup>`.
 
 <ExampleSnippet component="ButtonGroupExample" componentName="React Button Group" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  For assistive technologies (ex. screen readers) to communicate that a series of buttons are grouped, a proper <code>role</code> attribute has to be provided. For button groups, this should be <code>role="group"</code>, while toolbars should have a <code>role="toolbar"</code>.
+<Callout color="info" title={<>Ensure the correct <code>role</code> and provide a label</>}>
+  For assistive technologies (ex. screen readers) to communicate that a series of buttons are grouped, a proper `role` attribute has to be provided. For button groups, this should be `role="group"`, while toolbars should have a `role="toolbar"`.
 
-  Besides, groups and toolbars should be provided an understandable label, as most assistive technologies will otherwise not declare them, despite the appearance of the specific role attribute. In the following examples provided here, we apply <code>aria-label</code>, but options such as <code>aria-labelledby</code> can also be used.
+  Besides, groups and toolbars should be provided an understandable label, as most assistive technologies will otherwise not declare them, despite the appearance of the specific role attribute. In the following examples provided here, we apply `aria-label`, but options such as `aria-labelledby` can also be used.
 </Callout>
 
 These classes can also be added to groups of links, as an alternative to the [`CNav`](./../navs-tabs/#base-nav) components.

diff --git a/packages/docs/content/components/button/index.mdx b/packages/docs/content/components/button/index.mdx
@@ -12,12 +12,7 @@ CoreUI includes a bunch of predefined buttons components, each serving its own s
 
 <ExampleSnippet component="ButtonExample" componentName="React Button" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  Using color to add meaning only provides a visual indication, which will not be conveyed to users
-  of assistive technologies – such as screen readers. Ensure that information denoted by the color
-  is either obvious from the content itself (e.g. the visible text), or is included through
-  alternative means, such as additional text hidden with the `.visually-hidden` class.
-</Callout>
+<Callout color="warning" type="colorAssistiveTechnologies" />
 
 ## Disable text wrapping
 

diff --git a/packages/docs/content/components/callout/index.mdx b/packages/docs/content/components/callout/index.mdx
@@ -12,12 +12,7 @@ Callout component is prepared for any length of text, as well as an optional ele
 
 <ExampleSnippet component="CalloutExample" componentName="React Callout" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  Using color to add meaning only provides a visual indication, which will not be conveyed to
-  users of assistive technologies – such as screen readers. Ensure that information denoted by the
-  color is either obvious from the content itself (e.g. the visible text), or is included through
-  alternative means, such as additional text hidden with the `.visually-hidden` class.
-</Callout>
+<Callout color="warning" type="colorAssistiveTechnologies" />
 
 ## API
 

diff --git a/packages/docs/content/components/card/index.mdx b/packages/docs/content/components/card/index.mdx
@@ -140,12 +140,7 @@ Use `color` property to change the appearance of a card.
 
 <ExampleSnippet component="CardStylesBackgroundAndColorExample" componentName="React Card" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  Using color to add meaning only provides a visual indication, which will not be conveyed to
-  users of assistive technologies – such as screen readers. Ensure that information denoted by the
-  color is either obvious from the content itself (e.g. the visible text), or is included through
-  alternative means, such as additional text hidden with the `.visually-hidden` class.
-</Callout>
+<Callout color="warning" type="colorAssistiveTechnologies" />
 
 ### Border
 

diff --git a/packages/docs/content/components/list-group/index.mdx b/packages/docs/content/components/list-group/index.mdx
@@ -54,12 +54,7 @@ Contextual classes also work with `<a>`s or `<button>`s. Note the addition of th
 
 <ExampleSnippet component="ListGroupContextualClasses2Example" componentName="React List Group" />
 
-<Callout color="info" title="Conveying meaning to assistive technologies">
-  Using color to add meaning only provides a visual indication, which will not be conveyed to
-  users of assistive technologies – such as screen readers. Ensure that information denoted by the
-  color is either obvious from the content itself (e.g. the visible text), or is included through
-  alternative means, such as additional text hidden with the `.visually-hidden` class.
-</Callout>
+<Callout color="warning" type="colorAssistiveTechnologies" />
 
 ## With badges
 

diff --git a/packages/docs/content/customize/sass.mdx b/packages/docs/content/customize/sass.mdx
@@ -37,6 +37,23 @@ 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 color="info" type="dartSassModules" />
+
+```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 color="warning" type="dartSassDeprecations" />
+
 ```scss
 // Custom.scss
 // Option A: Include all of CoreUI
@@ -92,6 +109,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 color="info" type="dartSassModules" />
+
+```scss
+@use "@coreui/coreui/scss/coreui" with (
+  $body-bg: #000,
+  $body-color: #111
+)
+```
+
+<Callout color="warning" type="dartSassDeprecations" />
+
 ```scss
 // Required
 @import "../node_modules/@coreui/coreui/scss/functions";
@@ -142,6 +170,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 color="info" type="dartSassModules" />
+
+```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 color="warning" type="dartSassDeprecations" />
+
 ```scss
 // Create your own map
 $custom-colors: (
@@ -156,6 +201,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 color="info" type="dartSassModules" />
+
+```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 color="warning" type="dartSassDeprecations" />
+
 ```scss
 // Required
 @import "../node_modules/@coreui/coreui/scss/functions";
@@ -213,6 +273,8 @@ You can lighten or darken colors with CoreUI's `tint-color()` and `shade-color()
 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%);
 }
@@ -231,6 +293,8 @@ An additional function we include in CoreUI for Bootstrap is the color contrast
 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);
@@ -241,6 +305,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`
 }
@@ -249,6 +315,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`
 }
@@ -265,6 +333,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;
 
@@ -282,6 +352,8 @@ $border-width: 1px;
 Example where the calc is invalid:
 
 ```scss
+@use "@coreui/coreui/scss/functions/math" as *;
+
 $border-radius: .25rem;
 $border-width: 0;
 
@@ -304,15 +376,12 @@ Our `@coreui/coreui/scss/mixins/` directory has a ton of mixins that power parts
 
 A shorthand mixin for the `prefers-color-scheme` media query is available with support for `light`, `dark`, and custom color schemes.
 
-```scss
-@mixin color-scheme($name) {
-  @media (prefers-color-scheme: #{$name}) {
-    @content;
-  }
-}
-```
+
+<ScssDocs file="mixins/_color-scheme.scss" capture="mixin-color-scheme" />
 
 ```scss
+@use "@coreui/coreui/scss/mixins/color-scheme" as *;
+
 .custom-element {
   @include color-scheme(dark) {
     // Insert dark mode styles here

diff --git a/packages/docs/src/components/Callout.tsx b/packages/docs/src/components/Callout.tsx
@@ -2,14 +2,91 @@ import React, { FC, ReactNode } from 'react'
 export interface CalloutProps {
   children: ReactNode
   color: string
-  title?: string
+  title?: string | ReactNode
+  type?: string
 }
 
-const Callout: FC<CalloutProps> = ({ children, color, title }) => {
+const description = (type: string) => {
+  switch (type) {
+    case 'colorAssistiveTechnologies': {
+      return (
+        <>
+          <h5>Conveying meaning to assistive technologies</h5>
+          <p>
+            Using color to add meaning only provides a visual indication, which will not be conveyed
+            to users of assistive technologies – such as screen readers. Ensure that information
+            denoted by the color is either obvious from the content itself (e.g. the visible text),
+            or is included through alternative means, such as additional text hidden with the{' '}
+            <code>.visually-hidden</code> class.
+          </p>
+        </>
+      )
+    }
+    case 'dartSassModules': {
+      return (
+        <>
+          <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"
+              rel="noreferrer"
+            >
+              here
+            </a>
+            .
+          </p>
+        </>
+      )
+    }
+    case 'dartSassDeprecations': {
+      return (
+        <>
+          <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"
+              rel="noreferrer"
+            >
+              here
+            </a>
+            .
+          </p>
+        </>
+      )
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+const Callout: FC<CalloutProps> = ({ children, color, title, type }) => {
   return (
     <div className={`docs-callout docs-callout-${color}`}>
-      {title && <h5>{title}</h5>}
-      {children}
+      {type ? (
+        description(type)
+      ) : (
+        <>
+          {title && <h5>{title}</h5>}
+          {children}
+        </>
+      )}
     </div>
   )
 }

diff --git a/packages/docs/src/components/ScssDocs.tsx b/packages/docs/src/components/ScssDocs.tsx
@@ -7,6 +7,19 @@ export interface ScssDocsProps {
   capture: string
 }
 
+const unindent = (text: string) => {
+  const lines = text.split('\n')
+  // Find first non-empty line to determine indentation
+  const firstLine = lines.find((line) => line.trim().length > 0) || ''
+  const indentMatch = firstLine.match(/^( *)/)
+  const indent = indentMatch ? indentMatch[1] : ''
+  const regex = new RegExp(`^${indent}`)
+  return lines
+    .map((line) => line.replace(regex, ''))
+    .join('\n')
+    .trimEnd()
+}
+
 const ScssDocs = ({ file, capture }: ScssDocsProps) => {
   ;(typeof global === 'undefined' ? window : global).Prism = Prism
   // eslint-disable-next-line unicorn/prefer-module
@@ -31,11 +44,11 @@ const ScssDocs = ({ file, capture }: ScssDocsProps) => {
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const _file = data.allFile.edges.find((node: any) => node.node.relativePath === file)
-  const captureStart = `// scss-docs-start ${capture}`
-  const captureEnd = `// scss-docs-end ${capture}`
-  const re = new RegExp(`${captureStart}((?:.|\n)*)${captureEnd}`)
+  const captureStart = `// scss-docs-start ${capture}\n`
+  const captureEnd = `// scss-docs-end ${capture}\n`
+  const re = new RegExp(`${captureStart}([\\s\\S]*?)${captureEnd}`, 'm')
   const captured = re.exec(_file.node.internal.content)
-  const code = captured ? captured[1].trim() : undefined
+  const code = captured ? captured[1] : undefined
 
   if (code === undefined) {
     console.error(`Can't find "${capture}" in ${_file.node.relativePath}`)
@@ -45,10 +58,7 @@ const ScssDocs = ({ file, capture }: ScssDocsProps) => {
     code && (
       <div className="highlight mb-3">
         <Highlight
-          code={code
-            .replaceAll('--#{$prefix}', '--cui-')
-            .replaceAll('\n  -', '\n-')
-            .replaceAll('\n  @', '\n@')}
+          code={unindent(code).replaceAll('--#{$prefix}', '--cui-')}
           language="scss"
           theme={{ plain: {}, styles: [] }}
         >