feat(list): allow lists to be themeable

Author: NickDJM

dist/css/component.css.map

@@ -7,15 +7,42 @@
 // Those should be defined as custom properties in the `_variables.scss` file.
 
 @use "../../defaults" as root-defaults;
+@use "../../functions/theme";
+@use "sass:map";
 
 // Card 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;
+$themeable: false !default;
 $list-selector-base: $selector-base !default;
 $list-selector: "list" !default;
+$list-theme-selector-base: $modifier-selector-base !default;
+$list-theme-selector-prefix: "" !default;
 $list-item-selector-base: $selector-base !default;
 $list-item-selector: "list-item" !default;
 
 // List item properties.
 $list-item-transform: none !default;
 $list-item-hover-transform: $list-item-transform !default;
+
+// List state theme defaults.
+// This map defines the default colour shades applied to themed lists.
+// All theme variants will only adjust the colour and border colour of the list
+// container and items.
+$-list-theme-mappings: (
+  color: 900,
+  border-color: 700,
+  item-color: 900,
+  item-border-color: 700,
+);
+$list-theme-mappings: () !default;
+
+// Merge the custom list theme map with the default one.
+@if $generate-base-theme-map {
+  $list-theme-mappings: map.merge($-list-theme-mappings, $list-theme-mappings);
+}
+
+$-list-theme-map: theme.generate-property-map($list-theme-mappings);
+$list-theme-map: () !default;
+$list-theme-map: map.deep-merge($-list-theme-map, $list-theme-map);

dist/css/component/list.css.map

@@ -8,7 +8,7 @@
 //
 // The following custom properties can be used to customize the list component:
 // | Property                                       | Description                                          | Default Value                                                                                                                                                 |
-// | ---                                            | ---                                                  | ---                                                                                                                                                           |
+// | ---------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 // | `--graupl-list-padding-x`                      | Horizontal padding of the list.                      | `var(--graupl-spacer-0)`                                                                                                                                      |
 // | `--graupl-list-padding-y`                      | Vertical padding of the list.                        | `var(--graupl-spacer-0)`                                                                                                                                      |
 // | `--graupl-list-padding`                        | Shorthand padding of the list.                       | `var(--graupl-list-padding-y) var(--graupl-list-padding-x)`                                                                                                   |
@@ -35,16 +35,88 @@
 // | `--graupl-list-item-border-color`              | Border colour of list items.                         | `var(--graupl-list-item-color)`                                                                                                                               |
 //
 // The following sass variables can be used to customize the generation of the list component:
-// | Variable                     | Description                            | Default Value    |
-// | ---                          | ---                                    | ---              |
-// | `$selector-base`             | Selector base for the component.       | `"."`            |
-// | `$modifier-selector-base`    | Selector base for component modifiers. | `"."`            |
-// | `$list-selector-base`        | Selector base for the list container.  | `$selector-base` |
-// | `$list-selector`             | Selector for the list container.       | `"list"`         |
-// | `$list-item-selector-base`   | Selector base for list items.          | `$selector-base` |
-// | `$list-item-selector`        | Selector for list items.               | `"list-item"`    |
-// | `$list-item-transform`       | Base transform for list items.         | `none`           |
-// | `$list-item-hover-transform` | Hover transform for list items.        | `none`           |
+// | 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.         | `false`          |
+// | `$list-selector-base`        | Selector base for the list container.     | `$selector-base` |
+// | `$list-selector`             | Selector for the list container.          | `"list"`         |
+// | `$list-theme-selector-base`  | Selector base for theme modifiers.        | `"."`            |
+// | `$list-theme-selector-prefix`| Selector prefix for theme modifiers.      | `""`             |
+// | `$list-item-selector-base`   | Selector base for list items.             | `$selector-base` |
+// | `$list-item-selector`        | Selector for list items.                  | `"list-item"`    |
+// | `$list-item-transform`       | Base transform for list items.            | `none`           |
+// | `$list-item-hover-transform` | Hover transform for list items.           | `none`           |
+// | `$list-theme-mappings`       | Map of properties/shades for list themes. | `()`             |
+// | `$list-theme-map`            | Expanded map of properties/colors/shades. | `()`             |
+//
+// ## Using `$list-theme-mappings`
+//
+// `$list-theme-mappings` is a 1-level map of properties and shade values.
+//
+// e.g.
+// ```scss
+// $list-theme-mappings: (
+//   color: 900,
+//   border-color: 700,
+// )
+// ```
+//
+// This directly[1] maps to all list variants, telling them what shade to use for the base colour slots.
+// All list variants will use the following based on the example above:
+// - Primary lists will have their `--graupl-list-color` property set to `--graupl-theme-active--primary--900` and `--graupl-list-border-color` to `--graupl-theme-active--primary--700`,
+// - Secondary lists will use the same shades for the secondary palette, and
+// - Tertiary lists will use the same shades for the tertiary palette.
+//
+// You can use this to customize _all_ list variants in the same way.
+//
+// For example, if you use the following map:
+// ```scss
+// $list-theme-mappings: (
+//   color: 500,
+//   item-color: 500,
+// )
+// ```
+//
+// All list variants will use the following:
+// - Primary lists will have their `--graupl-list-color` and `--graupl-list-item-color` properties set to `--graupl-theme-active--primary--500`,
+// - Secondary lists will have theirs set to `--graupl-theme-active--secondary--500`, and
+// - Tertiary lists will have theirs set to `--graupl-theme-active--tertiary--500`.
+//
+// [1] `$list-theme-mappings` gets parsed into a larger, more explicit map: `$list-theme-map`.
+//
+// Using `$list-theme-map`
+//
+// `$list-theme-map` is a multi-level map of properties, colors, and shade values.
+//
+// e.g.
+// ```scss
+// $list-theme-map: (
+//   primary: (
+//     item-border-color: (
+//       color: secondary,
+//       shade: 700
+//     ),
+//   ),
+//   secondary: (
+//     item-border-color: (
+//       color: secondary,
+//       shade: 500
+//     ),
+//   ),
+//   tertiary: (
+//     item-border-color: (
+//       color: tertiary,
+//       shade: 300
+//     ),
+//   ),
+// )
+// ```
+//
+// This directly maps to all list variants, telling them what shade to use for said property.
+// You can use this to customize list variants individually.
 //
 // @example
 // <ul class="list">
@@ -63,6 +135,7 @@
 @use "../../defaults" as root-defaults;
 @use "../../mixins/animation";
 @use "../../mixins/layer" as *;
+@use "../../mixins/theme" as theme;
 @use "defaults";
 @use "sass:map";
 @use "variables" as *;
@@ -106,6 +179,22 @@
     border-color: $list-border-color;
     background: $list-background;
     color: $list-color;
+
+    @if root-defaults.$themeable-components and defaults.$themeable {
+      @include theme.generate-modifiers(
+        defaults.$list-theme-map,
+        defaults.$list-theme-selector-base,
+        defaults.$list-theme-selector-prefix,
+        "list-"
+      );
+      @include theme.generate-modifiers(
+        defaults.$list-theme-map,
+        defaults.$list-theme-selector-base,
+        defaults.$list-theme-selector-prefix,
+        "list-",
+        ""
+      );
+    }
   }
 
   // .list-item