@ulu/frontend 0.4.1 → 0.4.3

package/lib/scss/_themes.scss

@@ -0,0 +1,135 @@
+////
+/// @group themes
+/// Core configuration module for the themes system. 
+/// Used to orchestrate custom property variations (e.g., light/dark modes).
+/// - Note: This system is intended for switching context values like colors, box-shadows, and borders. 
+///   It is not recommended to use this for structural layout values like margins or padding. 
+///   For responsive or structural changes, rely on the layout/breakpoint modules or component modifiers.
+////
+
+@use "sass:map";
+@use "sass:list";
+@use "sass:meta";
+@use "utils";
+@use "cssvar";
+
+/// Module Settings
+/// @type Map
+/// @prop {String} default ["light"] The theme key output to :root
+/// @prop {Map} color-schemes [()] Maps theme names to their corresponding valid CSS color-scheme value (e.g. ("high-contrast": "dark")). Note: If a theme name is literally "light" or "dark", it does not need to be mapped here.
+/// @prop {Map} inverses [()] Maps theme names to their opposite theme name (e.g. ("light": "dark", "dark": "light")). Used to output the .theme-inverse utility.
+$config: (
+  "default" : "light",
+  "color-schemes" : (),
+  "inverses" : ()
+) !default;
+
+/// The themes map
+/// - Format: `("property-name": ("light": value, "dark": value))`
+/// @type Map
+
+$tokens: () !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+/// @example scss
+///   @include ulu.themes-set(( "default" : "dark" ));
+
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Set the theme variations
+/// @param {Map} $changes Map of theme variations to merge
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
+/// @example scss
+///   @include ulu.themes-set-tokens((
+///     "color-background": (
+///       "light": white,
+///       "dark": black
+///     )
+///   ));
+
+@mixin set-tokens($changes, $merge-mode: "deep") {
+  $tokens: utils.map-merge($tokens, $changes, $merge-mode) !global;
+}
+
+/// Get a config option
+/// @param {String} $name Name of property
+/// @example scss {compile} Example usage
+///   .test {
+///     content: ulu.themes-get("default");
+///   }
+/// @return {*} Resolved value 
+
+@function get($name) {
+  @return utils.require-map-get($config, $name, "themes [config]");
+}
+
+/// Helper function to safely get the color scheme
+/// @param {String} $theme-name The name of the theme to lookup
+/// @example scss {compile} Example usage
+///   .test {
+///     content: ulu.themes-get-color-scheme("dark");
+///   }
+/// @return {String|Null} The CSS color-scheme value or null
+
+@function get-color-scheme($theme-name) {
+  $schemes: get("color-schemes");
+  $mapped: map.get($schemes, $theme-name);
+
+  @if ($mapped) {
+    @return $mapped;
+  }
+
+  @if ($theme-name == "light" or $theme-name == "dark") {
+    @return $theme-name;
+  }
+
+  @warn "ULU Themes: No valid color-scheme mapped for theme '#{$theme-name}'. Please add it using `themes.set(( \"color-schemes\" : ( \"#{$theme-name}\": \"light|dark\" ) ))`. The `color-scheme` property will not be output for this theme.";
+  @return null;
+}
+
+/// Helper function to get all unique theme keys (e.g., 'light', 'dark') from the $themes map
+/// @return {List} A list of all unique theme string keys
+
+@function get-keys() {
+  $keys: ();
+  @each $prop, $theme-map in $tokens {
+    @if meta.type-of($theme-map) == 'map' {
+      @each $key, $val in $theme-map {
+        @if not list.index($keys, $key) {
+          $keys: list.append($keys, $key);
+        }
+      }
+    }
+  }
+  @return $keys;
+}
+
+/// Outputs css vars for a specific type from a theme map
+/// @param {String} $key The key used to retrieve values from the map.
+/// @param {Map} $tokens [$tokens] The map containing the values. Defaults to the internal $tokens map.
+/// @param {String} $prefix The optional prefix for CSS variables.
+/// @example scss {compile} Example usage
+///   @include ulu.themes-set-tokens((
+///     "color-background": (
+///       "light": white,
+///       "dark": black
+///     )
+///   ));
+///   :root {
+///     @include ulu.themes-declare("light");
+///   }
+
+@mixin declare($key, $tokens: $tokens, $prefix: cssvar.get("prefix")) {
+  @each $name, $definition in $tokens {
+    $value: map.get($definition, $key);
+    @if ($value) {
+      @include cssvar.declare($name, $value, $prefix);
+    }
+  }
+}
+
+
+

package/lib/scss/base/_index.scss

@@ -5,6 +5,7 @@
 
 @forward "root" as root-*;
 @forward "normalize" as normalize-*;
+@forward "themes" as themes-*;
 @forward "print" as print-*;
 @forward "color" as color-*;
 @forward "elements" as elements-*;
@@ -17,6 +18,7 @@
 @use "../utils";
 @use "normalize";
 @use "root";
+@use "themes";
 @use "elements";
 @use "print";
 @use "typography";
@@ -30,6 +32,7 @@
 $all-includes: (
   "normalize",
   "root",
+  "themes",
   "elements," 
   "print", 
   "elements", 
@@ -77,6 +80,9 @@ $current-includes: $all-includes;
   @if (list.index($includes, "root")) {
     @include root.styles;
   }
+  @if (list.index($includes, "themes")) {
+    @include themes.styles;
+  }
   @if (list.index($includes, "elements")) {
     @include elements.styles;
   }

package/lib/scss/base/_root.scss

@@ -8,6 +8,53 @@
 @use "../utils";
 @use "../cssvar";
 
+/// Module Settings
+/// @type Map
+/// @prop {Dimension} sticky-top-offset [0px]
+/// @prop {Dimension} sticky-bottom-offset [0px]
+
+$config: (
+  "sticky-top-offset": 0px,
+  "sticky-bottom-offset": 0px
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {String} $name Name of property
+@function get($name) {
+  @return utils.require-map-get($config, $name, "base root [config]");
+}
+
+/// Global root variables (CSS Custom Properties)
+/// @type Map
+$cssvars: () !default;
+
+/// Set global root variables
+/// - Supports mapping values to breakpoints. Values can be literal or a configuration map with `value` and `breakpoints` keys.
+/// @example scss Example usage with breakpoints
+///   @include ulu.base-root-set-cssvars((
+///     "base-color": red,
+///     "responsive-size": (
+///       "value": 1rem,
+///       "breakpoints": (
+///         "medium": (
+///           "direction": "up",
+///           "value": 2rem
+///         )
+///       )
+///     )
+///   ));
+/// @param {Map} $changes Map of changes
+/// @param {String} $merge-mode Merge mode see utils.map-merge() [null|"deep"|"overwrite"]
+@mixin set-cssvars($changes, $merge-mode: null) {
+  $cssvars: utils.map-merge($cssvars, $changes, $merge-mode) !global;
+}
+
 /// Output custom properties in :root for base stylesheet
 /// @example scss
 ///  @include ulu.base-root-styles();
@@ -18,13 +65,14 @@
   :root {
     @include custom-properties();
     @include cssvar.declare-breakpoint();
+    @include cssvar.declare-all($cssvars);
   }
 }
 
 /// Output custom properties for ulu
 
 @mixin custom-properties() {
-  --ulu-sticky-top-offset: 0px; // Should be adjusted by user
-  --ulu-sticky-bottom-offset: 0px; // Should be adjusted by user
+  --ulu-sticky-top-offset: #{ get("sticky-top-offset") }; // Should be adjusted by user
+  --ulu-sticky-bottom-offset: #{ get("sticky-bottom-offset") }; // Should be adjusted by user
   --ulu-scrollbar-width: 0px; // Needs to be set by JS
 }

package/lib/scss/base/_themes.scss

@@ -0,0 +1,143 @@
+////
+/// @group themes
+/// Output base themes stylesheets
+////
+
+@use "sass:list";
+@use "sass:string";
+@use "sass:map";
+@use "../utils";
+@use "../themes";
+@use "../cssvar";
+@use "../selector";
+
+/// Module Settings
+/// @type Map
+/// @prop {Boolean} output-inverse [true] Whether to output the `.theme-inverse` utility and corresponding inverse variables
+/// @prop {Color} fake-dark-color [white] The fallback text color applied to elements using the `.theme-dark-fake` utility
+/// @prop {String} fake-dark-filter [invert(1) hue-rotate(180deg) saturate(0.7)] The filter applied to elements using the `.theme-dark-fake` utility
+$config: (
+  "output-inverse": true,
+  "fake-dark-color": white,
+  "fake-dark-filter": invert(1) hue-rotate(180deg) saturate(0.7)
+) !default;
+
+/// Change modules $config
+/// @param {Map} $changes Map of changes
+@mixin set($changes) {
+  $config: map.merge($config, $changes) !global;
+}
+
+/// Get a config option
+/// @param {String} $name Name of property
+@function get($name) {
+  @return utils.require-map-get($config, $name, "base themes [config]");
+}
+
+/// Outputs base theme variables and classes
+/// @example scss
+///   @include ulu.base-themes-styles();
+@mixin styles {
+  @include utils.file-header('base', 'themes');
+
+  @if (list.length(themes.$tokens) > 0) {
+    $keys: themes.get-keys();
+    $default: themes.get("default");
+    $prefix: selector.class("theme");
+    $dark-selectors: ();
+    $inverses: themes.get("inverses");
+    $inverse-prefix: selector.class("theme-inverse");
+    $output-inverse: get("output-inverse");
+    
+    // 1. Build Base Themes
+    @each $key in $keys {
+      $selectors: ();
+      $selectors: list.append($selectors, "#{ $prefix }-#{ $key }", comma);
+      
+      @if ($key == $default) {
+        $selectors: list.append($selectors, ":root", comma);
+      }
+
+      #{ $selectors } {
+        // Standard color-scheme and CSS vars
+        $color-scheme: themes.get-color-scheme($key);
+        @if ($color-scheme) {
+          color-scheme: #{ $color-scheme };
+        }
+        @include themes.declare($key);
+
+        // Optional Inverse Variables (Variable Swap Approach)
+        // Can use @scope in the future but for now we suffix -"inverse"
+        @if ($output-inverse) {
+          $inverse-key: map.get($inverses, $key);
+          @if ($inverse-key) {
+            $inv-scheme: themes.get-color-scheme($inverse-key);
+            @if ($inv-scheme) {
+              --ulu-inverse-color-scheme: #{ $inv-scheme };
+            }
+            
+            @each $prop, $theme-map in themes.$tokens {
+              @if (utils.is-map($theme-map)) {
+                $inv-value: map.get($theme-map, $inverse-key);
+                @if ($inv-value) {
+                  // Only output the inverse variable, not its fallback!
+                  @include cssvar.declare("inverse-#{$prop}", $inv-value);
+                }
+              }
+            }
+          }
+        }
+
+        // Contextual trigger for the fake dark utility
+        @if ($color-scheme == "dark") {
+          --ulu-theme-fake-filter: #{ get("fake-dark-filter") };
+          --ulu-theme-fake-color: #{ get("fake-dark-color") };
+        } @else {
+          --ulu-theme-fake-filter: none;
+          --ulu-theme-fake-color: inherit;
+        }
+      }
+
+      // Collect dark themes for the fake utility
+      @if (themes.get-color-scheme($key) == "dark") {
+        $dark-selectors: list.append($dark-selectors, $selectors, comma);
+        // Ensure fake dark applies to inverted light themes
+        @each $current-theme, $inverse-target in $inverses {
+          @if ($inverse-target == $key) {
+             $dark-selectors: list.append($dark-selectors, "#{ $prefix }-#{ $current-theme } #{ $inverse-prefix }", comma);
+             @if ($current-theme == $default) {
+               $dark-selectors: list.append($dark-selectors, ":root #{ $inverse-prefix }", comma);
+             }
+          }
+        }
+      }
+    }
+
+    // 2. The Inverse Utility Class
+    @if ($output-inverse and list.length(map.keys($inverses)) > 0) {
+      #{ $inverse-prefix } {
+        color-scheme: var(--ulu-inverse-color-scheme, inherit);
+        @each $prop, $theme-map in themes.$tokens {
+          @if (utils.is-map($theme-map)) {
+            $inv-name: cssvar.name("inverse-" + $prop);
+            // Swap them: --site-color-bg: var(--site-inverse-color-bg)
+            @include cssvar.declare($prop, var(#{ $inv-name }));
+          }
+        }
+      }
+    }
+
+    // 3. The Fake Dark Utility Class
+    /// Can be used on elements that need dark mode but that have colors that can't be updated (canvas charts for example)
+    /// It inverts the items color, and then inverts/spins the element colors so they match the hue before inversion
+    /// It also decreases the contrast slightly
+    @if (list.length($dark-selectors) > 0) {
+      #{ $dark-selectors } {
+        #{ $prefix }-dark-fake {
+          filter: var(--ulu-theme-fake-filter, none);
+          color: var(--ulu-theme-fake-color, inherit);
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A framework-agnostic frontend toolkit providing a modular, tree-shakable library of accessible components and utilities. Designed for seamless integration, it features a highly configurable SCSS system for any environment and vanilla JavaScript modules optimized for traditional websites and content management systems.",
   "type": "module",
   "files": [