@graupl/core 1.0.0-beta.22 → 1.0.0-beta.24

package/src/scss/component/alert/_defaults.scss

@@ -11,17 +11,30 @@
 @use "sass:map";
 
 // Alert selectors.
+$selector-base: root-defaults.$component-selector-base !default;
+$modifier-selector-base: root-defaults.$modifier-selector-base !default;
 $generate-base-theme-map: root-defaults.$generate-base-theme-maps !default;
-$alert-selector: ".alert" !default;
-$alert-theme-selector-prefix: "." !default;
-$alert-body-selector: ".alert-body" !default;
-$alert-header-selector: ".alert-header" !default;
-$alert-footer-selector: ".alert-footer" !default;
-$alert-title-selector: ".alert-title" !default;
-$alert-dismisser-selector: ".alert-dismisser" !default;
-$alert-hidden-selector: ".hide" !default;
-$alert-shown-selector: ".show" !default;
-$alert-transition-selector: ".transitioning" !default;
+$themeable: true !default;
+$alert-selector-base: $selector-base !default;
+$alert-selector: "alert" !default;
+$alert-theme-selector-base: $modifier-selector-base !default;
+$alert-theme-selector-prefix: "" !default;
+$alert-body-selector-base: $selector-base !default;
+$alert-body-selector: "alert-body" !default;
+$alert-header-selector-base: $selector-base !default;
+$alert-header-selector: "alert-header" !default;
+$alert-footer-selector-base: $selector-base !default;
+$alert-footer-selector: "alert-footer" !default;
+$alert-title-selector-base: $selector-base !default;
+$alert-title-selector: "alert-title" !default;
+$alert-dismisser-selector-base: $selector-base !default;
+$alert-dismisser-selector: "alert-dismisser" !default;
+$alert-hidden-selector-base: $modifier-selector-base !default;
+$alert-hidden-selector: "hide" !default;
+$alert-shown-selector-base: $modifier-selector-base !default;
+$alert-shown-selector: "show" !default;
+$alert-transition-selector-base: $modifier-selector-base !default;
+$alert-transition-selector: "transitioning" !default;
 
 // Alert state theme defaults.
 // This map is used to define the default colour shades for the
@@ -45,30 +58,8 @@ $-alert-theme-mappings: (
   link-active-color: 900,
   link-disabled-color: 400,
 );
-$custom-alert-state-theme-map: () !default;
-$alert-state-theme-map: () !default;
 $alert-theme-mappings: () !default;
 
-// @todo remove this once $custom-alert-state-theme-map is removed
-@if $custom-alert-state-theme-map != () {
-  @warn "`$custom-alert-state-theme-map` is deprecated and will be removed in a future release of Graupl. Use `$alert-theme-mappings` instead.";
-
-  $alert-state-theme-map: map.merge(
-    $alert-theme-mappings,
-    $custom-alert-state-theme-map
-  );
-}
-
-// @todo remove the once $alert-state-theme-map is removed
-@if $alert-state-theme-map != () {
-  @warn "`$alert-state-theme-map` is deprecated and will be removed in a future release of Graupl. Use `$alert-theme-mappings` instead.";
-
-  $alert-theme-mappings: map.merge(
-    $alert-theme-mappings,
-    $alert-state-theme-map
-  );
-}
-
 // Merge the custom alert state theme map with the default one.
 @if $generate-base-theme-map {
   $alert-theme-mappings: map.merge(

package/src/scss/component/alert/_index.scss

@@ -1,23 +1,219 @@
 // @graupl/core alert component styles.
+//
+// This module provides the alert component styles.
+//
+// The following selectors are generated by default:
+// - `.alert`: The alert container.
+// - `.alert-body`: The alert body content.
+// - `.alert-header`: The alert header content.
+// - `.alert-footer`: The alert footer content.
+// - `.alert-title`: The alert title element.
+// - `.alert-dismisser`: The alert dismisser control.
+// - `.show`: Modifier applied when the alert is shown.
+// - `.hide`: Modifier applied when the alert is hidden.
+// - `.transitioning`: Modifier applied while the alert is transitioning.
+//
+// The following custom properties can be used to customize the alert component:
+// | Property                                   | Description                                | Default Value                                                                                                                                                                        |
+// | ---                                        | ---                                        | ---                                                                                                                                                                                  |
+// | `--graupl-alert-padding-x`                 | Horizontal padding of the alert.           | `var(--graupl-spacer-5)`                                                                                                                                                             |
+// | `--graupl-alert-padding-y`                 | Vertical padding of the alert.             | `var(--graupl-spacer-5)`                                                                                                                                                             |
+// | `--graupl-alert-padding`                   | Shorthand padding of the alert.            | `var(--graupl-alert-padding-y) var(--graupl-alert-padding-x)`                                                                                                                        |
+// | `--graupl-alert-gap`                       | Gap inside the alert (column/row).         | `var(--graupl-alert-column-gap) var(--graupl-alert-row-gap)`                                                                                                                         |
+// | `--graupl-alert-background`                | Background colour of the alert.            | `var(--graupl-background)`                                                                                                                                                           |
+// | `--graupl-alert-color`                     | Text colour of the alert.                  | `var(--graupl-color)`                                                                                                                                                                |
+// | `--graupl-alert-border-width`              | Border width of the alert.                 | `var(--graupl-border-top-width) var(--graupl-border-right-width) var(--graupl-border-bottom-width) var(--graupl-border-left-width)`                                                  |
+// | `--graupl-alert-border-style`              | Border style of the alert.                 | `var(--graupl-border-top-style) var(--graupl-border-right-style) var(--graupl-border-bottom-style) var(--graupl-border-left-style)`                                                  |
+// | `--graupl-alert-border-radius`             | Border radius of the alert.                | `var(--graupl-border-top-left-radius) var(--graupl-border-top-right-radius) var(--graupl-border-bottom-right-radius) var(--graupl-border-bottom-left-radius)`                        |
+// | `--graupl-alert-border-color`              | Border colour of the alert.                | `var(--graupl-alert-color)`                                                                                                                                                          |
+// | `--graupl-alert-transition`                | Transition applied to alert appearance.    | `opacity var(--graupl-transition-duration-fast) var(--graupl-transition-timing-function), transform var(--graupl-transition-duration-fast) var(--graupl-transition-timing-function)` |
+// | `--graupl-alert-transition-reduced-motion` | Transition when reduced motion is enabled. | `opacity var(--graupl-transition-duration-fast) var(--graupl-transition-timing-function)`                                                                                            |
+// | `--graupl-alert-header-padding`            | Padding for the alert header.              | `0 0`                                                                                                                                                                                |
+// | `--graupl-alert-body-padding`              | Padding for the alert body.                | `0 0`                                                                                                                                                                                |
+// | `--graupl-alert-footer-padding`            | Padding for the alert footer.              | `0 0`                                                                                                                                                                                |
+// | `--graupl-alert-title-color`               | Text colour of the alert title.            | `var(--graupl-alert-color)`                                                                                                                                                          |
+// | `--graupl-alert-title-font-size`           | Font size of the alert title.              | `var(--graupl-h4)`                                                                                                                                                                   |
+// | `--graupl-alert-title-font-weight`         | Font weight of the alert title.            | `var(--graupl-font-weight-h4)`                                                                                                                                                       |
+// | `--graupl-alert-title-font-family`         | Font family of the alert title.            | `var(--graupl-font-family-h4)`                                                                                                                                                       |
+// | `--graupl-alert-title-line-height`         | Line height of the alert title.            | `var(--graupl-line-height-h4)`                                                                                                                                                       |
+// | `--graupl-alert-title-margin`              | Margin for the alert title.                | `0 0 0 0`                                                                                                                                                                            |
+// | `--graupl-alert-link-color`                | Link colour inside alerts.                 | `unset` (inherits)                                                                                                                                                                   |
+// | `--graupl-alert-link-visited-color`        | Visited link colour inside alerts.         | `unset`                                                                                                                                                                              |
+// | `--graupl-alert-link-focus-color`          | Focused link colour inside alerts.         | `unset`                                                                                                                                                                              |
+// | `--graupl-alert-link-hover-color`          | Hovered link colour inside alerts.         | `unset`                                                                                                                                                                              |
+// | `--graupl-alert-link-active-color`         | Active link colour inside alerts.          | `unset`                                                                                                                                                                              |
+// | `--graupl-alert-link-disabled-color`       | Disabled link colour inside alerts.        | `unset`                                                                                                                                                                              |
+//
+// The following sass variables can be used to customize the generation of the alert component:
+// | Variable                          | Description                                   | Default Value       |
+// | ---                               | ---                                           | ---                 |
+// | `$selector-base`                  | Selector base for the component.              | `"."`               |
+// | `$modifier-selector-base`         | Selector base for component modifiers.        | `"."`               |
+// | `$generate-base-theme-map`        | Flag to generate the base theme map.          | `true`              |
+// | `$themeable`                      | Flag to generate theme modifiers.             | `true`              |
+// | `$alert-selector-base`            | Selector base for the alert container.        | `$selector-base`    |
+// | `$alert-selector`                 | Selector for the alert container.             | `"alert"`           |
+// | `$alert-theme-selector-base`      | Selector base for theme modifiers.            | `"."`               |
+// | `$alert-theme-selector-prefix`    | Selector prefix for theme modifiers.          | `""`                |
+// | `$alert-body-selector-base`       | Selector base for the alert body.             | `$selector-base`    |
+// | `$alert-body-selector`            | Selector for the alert body.                  | `"alert-body"`      |
+// | `$alert-header-selector-base`     | Selector base for the alert header.           | `$selector-base`    |
+// | `$alert-header-selector`          | Selector for the alert header.                | `"alert-header"`    |
+// | `$alert-footer-selector-base`     | Selector base for the alert footer.           | `$selector-base`    |
+// | `$alert-footer-selector`          | Selector for the alert footer.                | `"alert-footer"`    |
+// | `$alert-title-selector-base`      | Selector base for the alert title.            | `$selector-base`    |
+// | `$alert-title-selector`           | Selector for the alert title.                 | `"alert-title"`     |
+// | `$alert-dismisser-selector-base`  | Selector base for the alert dismisser.        | `$selector-base`    |
+// | `$alert-dismisser-selector`       | Selector for the alert dismisser.             | `"alert-dismisser"` |
+// | `$alert-hidden-selector-base`     | Selector base for the hidden modifier.        | `"."`               |
+// | `$alert-hidden-selector`          | Selector applied when hidden.                 | `"hide"`            |
+// | `$alert-shown-selector-base`      | Selector base for the shown modifier.         | `"."`               |
+// | `$alert-shown-selector`           | Selector applied when shown.                  | `"show"`            |
+// | `$alert-transition-selector-base` | Selector base for the transitioning modifier. | `"."`               |
+// | `$alert-transition-selector`      | Selector applied while transitioning.         | `"transitioning"`   |
+//
+// ## Using `$alert-theme-mappings`
+//
+// `$alert-theme-mappings` is a 1-level map of properties and shade values.
+//
+// e.g.
+// ```scss
+// $alert-theme-mappings: (
+//   border-color: 700,
+// )
+// ```
+//
+// This directly[1] maps to all alert variants, telling them what shade to use for said property.
+// All alert variants will use the following based on the example above:
+// - Primary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--primary--700`,
+// - Secondary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--tertiary--700`.
+//
+// You can use this to customize _all_ alerts variants in the same way.
+//
+// For example, if you use the following map:
+// ```scss
+// $alert-theme-mappings: (
+//   border-color: 500,
+// )
+// ```
+//
+// All alert variants will use the following:
+// - Primary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--primary--500`,
+// - Secondary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--500`, and
+// - Tertiary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--tertiary--500`.
+//
+// [1] `$alert-theme-mappings` gets parsed into a larger, more explicit map: `$alert-theme-map`.
+//
+// Using `$alert-theme-map`
+//
+// `$alert-theme-map` is a multi-level map of properties, colors, and shade values.
+//
+// e.g.
+// ```scss
+// $alert-theme-map: (
+//   primary: (
+//     border-color: (
+//       color: primary,
+//       shade: 700
+//     ),
+//   ),
+//   secondary: (
+//     border-color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   tertiary: (
+//     border-color: (
+//       color: tertiary,
+//       shade: 700
+//     ),
+//   ),
+// )
+// ```
+//
+// This directly maps to all alert variants, telling them what shade to use for said property.
+// The alert variants will use the following based on the example above:
+// - Primary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--primary--700`,
+// - Secondary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--tertiary--700`.
+//
+// You can use this to customize alert variants individually.
+//
+// For example, if you use the following map:
+//
+// ```scss
+// $alert-theme-map: (
+//   primary: (
+//     border-color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   secondary: (
+//     border-color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   tertiary: (
+//     border-color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+// )
+// ```
+//
+// The alert variants will use the following:
+// - Primary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--700`,
+// - Secondary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary alerts will have their `--graupl-alert-border-color` property set to `--graupl-theme-active--secondary--700`.
+//
+// @example
+// <div class="alert">
+//   <div class="alert-header">
+//     <h3 class="alert-title">Alert</h3>
+//   </div>
+//   <div class="alert-body">
+//     <p>This is some text that describes the alert.</p>
+//   </div>
+// </div>
+//
+// @example
+// <div class="alert primary">
+//   <div class="alert-header">
+//     <h3 class="alert-title">Alert</h3>
+//   </div>
+//   <div class="alert-body">
+//     <p>This is some text that describes the alert.</p>
+//   </div>
+//   <div class="alert-footer">
+//     <a href="#">Action</a>
+//   </div>
+//   <button class="alert-dismisser">x</button>
+// </div>
 
 @use "defaults";
 @use "variables" as *;
 @use "../../defaults" as root-defaults;
-@use "../../theme/color/variables" as color;
 @use "../../mixins/layer" as *;
 @use "../../mixins/animation";
-@use "../../functions/theme";
+@use "../../mixins/theme";
 @use "../../base/button/mixins" as button-mixins;
 @use "sass:map";
 
 @include layer(base) {
-  #{defaults.$alert-dismisser-selector} {
+  // .alert-dismisser
+  #{defaults.$alert-dismisser-selector-base}#{defaults.$alert-dismisser-selector} {
     @include button-mixins.apply-base;
   }
 }
 
 @include layer(component) {
-  #{defaults.$alert-selector} {
+  // .alert
+  #{defaults.$alert-selector-base}#{defaults.$alert-selector} {
     --#{root-defaults.$prefix}button-border: 0;
 
     display: grid;
@@ -30,57 +226,67 @@
     border-radius: $alert-border-radius;
     gap: $alert-gap;
 
-    &#{defaults.$alert-hidden-selector} {
+    // &.hide
+    &#{defaults.$alert-hidden-selector-base}#{defaults.$alert-hidden-selector} {
       display: none;
     }
 
-    &#{defaults.$alert-transition-selector} {
+    // &.transitioning
+    &#{defaults.$alert-transition-selector-base}#{defaults.$alert-transition-selector} {
       display: grid;
       opacity: 0;
     }
 
-    &#{defaults.$alert-shown-selector} {
+    // &.show
+    &#{defaults.$alert-shown-selector-base}#{defaults.$alert-shown-selector} {
       display: grid;
     }
-
-    @include animation.off {
-      #{defaults.$alert-selector} {
-        --#{root-defaults.$prefix}alert-transition: #{$alert-transition-reduced-motion};
-      }
-    }
   }
 
-  #{defaults.$alert-header-selector} {
+  // .alert-header
+  #{defaults.$alert-header-selector-base}#{defaults.$alert-header-selector} {
     grid-column: content;
     grid-row: header;
     padding: $alert-header-padding;
   }
 
-  #{defaults.$alert-body-selector} {
+  // .alert-body
+  #{defaults.$alert-body-selector-base}#{defaults.$alert-body-selector} {
     grid-column: content;
     grid-row: body;
     padding: $alert-body-padding;
   }
 
-  #{defaults.$alert-footer-selector} {
+  // .alert-footer
+  #{defaults.$alert-footer-selector-base}#{defaults.$alert-footer-selector} {
     grid-column: content;
     grid-row: footer;
     padding: $alert-footer-padding;
   }
 
-  #{defaults.$alert-dismisser-selector} {
+  // .alert-dismisser
+  #{defaults.$alert-dismisser-selector-base}#{defaults.$alert-dismisser-selector} {
     grid-column: dismiss;
     grid-row: 1 / -1;
     align-self: flex-start;
   }
 
-  #{defaults.$alert-title-selector} {
+  // .alert-title
+  #{defaults.$alert-title-selector-base}#{defaults.$alert-title-selector} {
     margin: $alert-title-margin;
   }
+
+  @include animation.off {
+    // .alert
+    #{defaults.$alert-selector-base}#{defaults.$alert-selector} {
+      --#{root-defaults.$prefix}alert-transition: #{$alert-transition-reduced-motion};
+    }
+  }
 }
 
 @include layer(theme) {
-  #{defaults.$alert-selector} {
+  // .alert
+  #{defaults.$alert-selector-base}#{defaults.$alert-selector} {
     --#{root-defaults.$prefix}button-background: #{$alert-background};
     --#{root-defaults.$prefix}button-focus-background: #{$alert-background};
     --#{root-defaults.$prefix}link-color: #{$alert-link-color};
@@ -94,23 +300,23 @@
     background-color: $alert-background;
     color: $alert-color;
 
-    @each $color, $map in defaults.$alert-theme-map {
-      &#{defaults.$alert-theme-selector-prefix}#{$color} {
-        @each $prop, $value in $map {
-          --#{root-defaults.$prefix}alert-#{$prop}: #{theme.get(
-              map.get($value, color),
-              map.get($value, shade)
-            )};
-        }
-      }
+    @if root-defaults.$themeable-components and defaults.$themeable {
+      @include theme.generate-modifiers(
+        defaults.$alert-theme-map,
+        defaults.$alert-theme-selector-base,
+        defaults.$alert-theme-selector-prefix,
+        "alert-"
+      );
     }
   }
 
-  #{defaults.$alert-dismisser-selector} {
+  // .alert-dismisser
+  #{defaults.$alert-dismisser-selector-base}#{defaults.$alert-dismisser-selector} {
     @include button-mixins.apply-theme;
   }
 
-  #{defaults.$alert-title-selector} {
+  // .alert-title
+  #{defaults.$alert-title-selector-base}#{defaults.$alert-title-selector} {
     color: $alert-title-color;
     font-size: $alert-title-font-size;
     font-weight: $alert-title-font-weight;