@graupl/icons 1.0.0-beta.25 → 1.0.0-beta.26

package/src/scss/component/icon/_index.scss

@@ -1,30 +1,174 @@
-// @gruapl/icons icon component styles.
+// @graupl/icons icon component styles.
+//
+// This module provides the icon component styles and theming hooks.
+//
+// The following selectors are generated by default:
+// - `.icon`: Base icon element.
+// - `.icon-before`: Pseudo-style helper for adding icons before content.
+// - `.icon-after`: Pseudo-style helper for adding icons after content.
+//
+// The following custom properties can be used to customize the icon component:
+// | Property                | Description                                  | Default Value               |
+// | ----------------------- | -------------------------------------------- | --------------------------- |
+// | `--graupl-icon-display` | Display value applied to the icon.           | `inline-block`              |
+// | `--graupl-icon-size`    | Base size for the icon box.                  | `1.25em`                    |
+// | `--graupl-icon-width`   | Width of the icon.                           | `var(--graupl-icon-size)`   |
+// | `--graupl-icon-height`  | Height of the icon.                          | `var(--graupl-icon-size)`   |
+// | `--graupl-icon-color`   | Color applied to the icon fill/mask.         | `var(--graupl-color)`       |
+// | `--graupl-icon`         | Source for the icon (mask-image/background). | `none`                      |
+// | `--graupl-icon-spacer`  | Spacer size used when placing the icon.      | `var(--graupl-spacer-2)`    |
+//
+// The following sass variables can be used to customize the generation of the icon 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 base theme maps for icon variants.                 | `true`                    |
+// | `$themeable`                     | Flag to generate theme modifiers.                                   | `true`                    |
+// | `$icon-selector-base`            | Selector base for the icon element.                                 | `$selector-base`          |
+// | `$icon-selector`                 | Selector for the icon element.                                      | `"icon"`                  |
+// | `$icon-before-selector`          | Selector for the before helper.                                     | `"icon-before"`           |
+// | `$icon-after-selector`           | Selector for the after helper.                                      | `"icon-after"`            |
+// | `$icon-theme-selector-base`      | Selector base used for theme modifiers.                             | `$modifier-selector-base` |
+// | `$icon-theme-selector-prefix`    | Selector prefix used for theme modifiers.                           | `""`                      |
+// | `$icon-prefix-selector-base`     | Selector base for icon name modifiers.                              | `$modifier-selector-base` |
+// | `$icon-prefix-selector`          | Selector used for icon name modifiers.                              | `""`                      |
+// | `$icon-display`                  | Default display value applied to icons.                             | `inline-block`            |
+// | `$icon-size`                     | Default size used for icon width/height.                            | `1.25em`                  |
+// | `$icons`                         | Map of icon names to their SVG data/URLs.                           | `()`                      |
+// | `$icon-theme-mappings`           | Map of properties and color shades used to generate icon variants.  | `()`                      |
+// | `$icon-theme-map`                | Resolved map of properties, colors, and shades for icon variants.   | `()`                      |
+//
+// ## Using `$icon-theme-mappings`
+//
+// `$icon-theme-mappings` is a 1-level map of properties and shade values.
+//
+// e.g.
+// ```scss
+// $icon-theme-mappings: (
+//   color: 700,
+// );
+// ```
+//
+// This directly maps to all icon variants, telling them what shade to use for the given property.
+// All icon variants will use the following based on the example above:
+// - Primary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--primary--700`,
+// - Secondary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--tertiary--700`.
+//
+// You can use this to customize _all_ icon variants in the same way.
+//
+// For example:
+// ```scss
+// $icon-theme-mappings: (
+//   color: 500,
+// );
+// ```
+//
+// All icon variants will use the following:
+// - Primary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--primary--500`,
+// - Secondary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--500`, and
+// - Tertiary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--tertiary--500`.
+//
+// [1] `$icon-theme-mappings` gets parsed into a larger, more explicit map: `$icon-theme-map`.
+//
+// Using `$icon-theme-map`
+//
+// `$icon-theme-map` is a multi-level map of properties, colors, and shade values.
+//
+// e.g.
+// ```scss
+// $icon-theme-map: (
+//   primary: (
+//     color: (
+//       color: primary,
+//       shade: 700
+//     ),
+//   ),
+//   secondary: (
+//     color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   tertiary: (
+//     color: (
+//       color: tertiary,
+//       shade: 700
+//     ),
+//   ),
+// )
+// ```
+//
+// This directly maps to all icon variants, telling them what shade to use for said property.
+// The icon variants will use the following based on the example above:
+// - Primary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--primary--700`,
+// - Secondary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--tertiary--700`.
+//
+// You can use this to customize icon variants individually.
+//
+// For example, if you use the following map:
+//
+// ```scss
+// $icon-theme-map: (
+//   primary: (
+//     color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   secondary: (
+//     color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   tertiary: (
+//     color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+// )
+// ```
+//
+// The icon variants will use the following:
+// - Primary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--700`,
+// - Secondary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--700`, and
+// - Tertiary icons will have their `--graupl-icon-color` property set to `--graupl-theme-active--secondary--700`.
+
+// @example
+// <span class="icon icon-search" aria-hidden="true"></span>
 
 @use "defaults";
 @use "pkg:@graupl/core/src/defaults" as root-defaults;
-@use "pkg:@graupl/core/src/functions/theme";
-@use "pkg:@graupl/core/src/theme/color/variables" as color;
 @use "pkg:@graupl/core/src/mixins/layer" as *;
 @use "mixins" as *;
 @use "sass:map";
 
 @include layer(component) {
+  // .icon
   #{defaults.$icon-selector-base}#{defaults.$icon-selector} {
     @include apply-component;
   }
 
+  // .icon-before
   #{defaults.$icon-selector-base}#{defaults.$icon-before-selector} {
     @include apply-component("before");
   }
 
+  // .icon-after
   #{defaults.$icon-selector-base}#{defaults.$icon-after-selector} {
     @include apply-component("after");
   }
 
+  // .icon, .icon-before, .icon-after
   #{defaults.$icon-selector-base}#{defaults.$icon-selector},
   #{defaults.$icon-selector-base}#{defaults.$icon-before-selector},
   #{defaults.$icon-selector-base}#{defaults.$icon-after-selector} {
     @each $name, $icon in defaults.$icons {
+      // &.[icon-name]
       &#{defaults.$icon-prefix-selector-base}#{defaults.$icon-prefix-selector}#{$name} {
         --#{root-defaults.$prefix}icon: #{$icon};
       }
@@ -33,35 +177,18 @@
 }
 
 @include layer(theme) {
+  // .icon
   #{defaults.$icon-selector-base}#{defaults.$icon-selector} {
     @include apply-theme;
   }
 
+  // .icon-before
   #{defaults.$icon-selector-base}#{defaults.$icon-before-selector} {
     @include apply-theme("before");
   }
 
+  // .icon-after
   #{defaults.$icon-selector-base}#{defaults.$icon-after-selector} {
     @include apply-theme("after");
   }
-
-  #{defaults.$icon-selector-base}#{defaults.$icon-selector},
-  #{defaults.$icon-selector-base}#{defaults.$icon-before-selector},
-  #{defaults.$icon-selector-base}#{defaults.$icon-after-selector} {
-    @each $color, $map in theme.get-colors() {
-      @each $shade, $value in $map {
-        $name: null;
-
-        @if $shade == "_default" {
-          $name: #{$color};
-        } @else {
-          $name: #{$color}-#{$shade};
-        }
-
-        &#{defaults.$icon-color-prefix-selector-base}#{defaults.$icon-color-prefix-selector}#{$name} {
-          --#{root-defaults.$prefix}icon-color: #{$value};
-        }
-      }
-    }
-  }
 }

package/src/scss/component/icon/_mixins.scss

@@ -1,61 +1,67 @@
 // @graupl/icons icon mixins.
 
+@use "defaults";
+@use "pkg:@graupl/core/src/defaults" as root-defaults;
+@use "pkg:@graupl/core/src/mixins/state";
+@use "pkg:@graupl/core/src/mixins/theme";
+@use "sass:map";
 @use "variables" as *;
 
-@mixin _component() {
-  display: $icon-display;
-  width: $icon-width;
-  height: $icon-height;
-  background-repeat: no-repeat;
-  background-position: center;
-  background-size: contain;
-  vertical-align: sub;
-  mask-image: $icon;
-  mask-repeat: no-repeat;
-  mask-size: contain;
-  mask-position: center;
-}
-
-@mixin _theme() {
-  background-color: $icon-color;
-}
+$-targets: (
+  "self": "&",
+  "before": "&::before",
+  "after": "&::after",
+);
 
+/// Mixin to apply component styles for icons.
 @mixin apply-component($target: "self") {
-  @if $target == "before" {
-    &::before {
-      @include _component;
+  #{map.get($-targets, $target)} {
+    display: $icon-display;
+    width: $icon-width;
+    height: $icon-height;
+    background-repeat: no-repeat;
+    background-position: center;
+    background-size: contain;
+    vertical-align: sub;
+    mask-image: $icon;
+    mask-repeat: no-repeat;
+    mask-size: contain;
+    mask-position: center;
 
+    @if $target == "before" or $target == "after" {
       content: "";
-      margin-inline-end: $icon-spacer;
     }
-  } @else if $target == "after" {
-    &::after {
-      @include _component;
-
-      content: "";
-      margin-inline-start: $icon-spacer;
-    }
-  } @else {
-    @include _component;
-
-    margin-inline: $icon-spacer $icon-spacer;
   }
 }
 
+/// Mixin to apply theme styles for icons.
 @mixin apply-theme($target: "self") {
-  @if $target == "before" {
-    &::before {
-      @include _theme;
-    }
-  } @else if $target == "after" {
-    &::after {
-      @include _theme;
-    }
-  } @else {
-    @include _theme;
+  @if root-defaults.$themeable-components and defaults.$themeable {
+    @include theme.generate-modifiers(
+      defaults.$icon-theme-map,
+      defaults.$icon-theme-selector-base,
+      defaults.$icon-theme-selector-prefix,
+      "icon-"
+    );
+  }
+
+  #{map.get($-targets, $target)} {
+    background-color: $icon-color;
   }
 }
 
+/// Mixin to bind icon colors to a component.
+///
+/// @param {CustomProperty} $color  - The default color prop for the icon.
+/// @param {Map}            $states - A map of states and color props for the icon.
+@mixin bind($color, $states) {
+  --#{root-defaults.$prefix}icon-color: #{$color};
+
+  @include state.generate-modifiers(
+    (--#{root-defaults.$prefix}icon-color: $states)
+  );
+}
+
 @mixin apply($target: "self") {
   @include apply-component($target);
   @include apply-theme($target);

package/src/scss/component/icon/_variables.scss

@@ -3,6 +3,17 @@
 // These values are to be used to directly style components and provide a
 // cleaner way to reference custom properties.
 
+// Custom property defaults:
+// | Property                  | Default                   |
+// | ------------------------- | ------------------------- |
+// | --graupl-icon-display     | inline-block              |
+// | --graupl-icon-size        | 1.25em                    |
+// | --graupl-icon-width       | var(--graupl-icon-size)   |
+// | --graupl-icon-height      | var(--graupl-icon-size)   |
+// | --graupl-icon-color       | var(--graupl-color)       |
+// | --graupl-icon             | none                      |
+// | --graupl-icon-spacer      | var(--graupl-spacer-2)    |
+
 @use "defaults";
 @use "pkg:@graupl/core/src/defaults" as root-defaults;
 @use "pkg:@graupl/core/src/theme/color/variables" as color;