@tylertech/forge 3.0.0-next.11 → 3.0.0-next.13

package/styles/color-picker/color-picker.scss

@@ -6,9 +6,6 @@
 @use '../theme';
 @use './mixins';
 
-// Required component styles
-@use '../icon-button/forge-icon-button';
-
 @include mixins.styles;
 
 :host {

package/styles/core/styles/_utils.scss

@@ -4,6 +4,7 @@
  * License: Apache-2.0
  */
 @use 'sass:map';
+@use 'sass:math';
 @use './core/config';
 
 ///
@@ -14,23 +15,77 @@
   @if not $value {
     @error 'Invalid #{$module} token: #{$key}';
   }
-  @return _create-var($module, $key, $value, $prefix);
+  @return create-var($module, $key, $value, $prefix);
 }
 
 ///
-/// Creates a CSS custom property declaration for a token in the provided module
+/// Creates a CSS custom property reference for a token in the provided module
 /// referencing an existing module token variable as the fallback.
 /// 
-@function module-ref($module, $token, $ref-token, $prefix: config.$prefix) {
-  @return _create-var($module, $token, var(--_#{$ref-token}), $prefix);
+/// To provide a module reference variable with a different fallback value, set the
+/// $type parameter to `value` and `$value` will be used verbatim.
+/// 
+/// Example:
+/// ```scss
+/// $my-token: module-ref(comp, color, primary-color); // => var(--forge-comp-color, var(--_primary-color));
+/// ```
+/// 
+@function module-ref($module, $token, $value, $type: ref, $prefix: config.$prefix) {
+  $fallback: if($type == ref, module-var($module, $value), $value);
+  @return create-var($module, $token, $fallback, $prefix);
 }
 
 ///
-/// Creates a CSS custom property declaration for a module token using the
+/// Creates an internal token reference variable for a module.
+///
+/// Example:
+/// ```sass
+/// color: #{module-var(color)}; // => color: var(--_component-name-color);
+/// ```
+/// 
+/// @param {String} $module - The module name.
+/// @param {String} $token - The token name.
+///
+@function module-var($module, $token, $prefix: config.$prefix) {
+  @return var(#{create-module-var($module, $token)});
+}
+
+///
+/// Creates a CSS custom property reference for a module token using the
 /// provided value as the variable fallback.
 /// 
+/// Example:
+/// ```scss
+/// $my-token: module-val(comp, color, red); // => var(--forge-comp-color, red);
+/// $my-other-token: module-val(comp, color, theme.variable(primary)); // => var(--forge-comp-color, var(--forge-theme-primary));
+/// ```
+/// 
 @function module-val($module, $token, $value, $prefix: config.$prefix) {
-  @return _create-var($module, $token, $value, $prefix);
+  @return create-var($module, $token, $value, $prefix);
+}
+
+///
+/// Creates a CSS custom property variable reference for a token in the provided module.
+/// 
+/// Example:
+/// ```scss
+/// $my-var: variable-ref(theme, color); // => var(--forge-theme-color);
+/// ```
+///
+@function variable-ref($module, $token, $value: null, $prefix: config.$prefix) {
+  @return create-var($module, $token, $value, $prefix);
+}
+
+///
+/// Creates a CSS custom property variable reference for a token in the provided module.
+/// 
+/// Example:
+/// ```scss
+/// $my-var: variable-ref(theme, color); // => var(--forge-theme-color);
+/// ```
+///
+@function variable-ref($module, $token, $value: null, $prefix: config.$prefix) {
+  @return create-var($module, $token, $value, $prefix);
 }
 
 ///
@@ -42,22 +97,104 @@
     @if not map.get($module-tokens, $token-name) {
       @error 'Invalid token "#{$token-name}" for module "#{$module}"';
     }
-    --#{$prefix}-#{$module}-#{$token-name}: #{$token-value};
+    @include declare-var($module, $token-name, $token-value, $prefix);
   }
 }
 
 ///
-/// Creates a new map by inheriting from a base map and overriding/adding values.
+/// Creates a token CSS custom property definition to point one token to another.
 /// 
+/// If `$new-token` is not a valid token then the provided value will be used verbatim.
+/// 
+/// Example:
+/// ```sass
+/// #{override(component-name, tokens, color, new-color)}; // => --_component-name-color: var(--_component-name-new-color);
+/// #{override(component-name, tokens, color, red)}; // => --_component-name-color: red;
+/// ```
+/// 
+/// @param {String} $module - The module name.
+/// @param {String} $module-tokens - The available tokens.
+/// @param {String} $token - The token name to override.
+/// @param {String} $token-or-value - The token name (if exists) or value to point to.
+/// @param {Boolean} $type - The type of token this is. Valid values are `token` and `value`.
+/// 
+@mixin override($module, $module-tokens, $token, $token-or-value, $type: token) {
+  @if $type == 'token' {
+    @if not map.get($module-tokens, $token) {
+      @error 'Invalid token "#{$token}" for module "#{$module}"';
+    }
+    @if not map.get($module-tokens, $token-or-value) {
+      @error 'Invalid override token "#{$token-or-value}" for module "#{$module}"';
+    }
+  }
+
+  // When the "token" type is specified, we output a module-level CSS custom property override
+  // that points to the provided token. This ensures that the module is taking ownership of the
+  // token value (which breaks the global cascading of internal tokens) and the module can choose
+  // to provide its own token specific to that override.
+  //
+  // When the "value" type is specified, we output a global-level CSS custom property override
+  // that points to the provided value. This keeps the global cascading of internal tokens intact
+  // instead of just overriding the token to a specific unchangeable value.
+  $value: if($type == 'token' and map.has-key($module-tokens, $token-or-value),
+              module-var($module, $token-or-value),
+              create-var($module, $token, $token-or-value));
+  #{create-module-var($module, $token)}: #{$value};
+}
+
+///
+/// Creates a new map by inheriting from a base map and overriding/adding values.
+///
 @function inherit-map($base, $overrides) {
   @return map.merge($base, $overrides);
 }
 
-
 ///
-/// Creates a CSS custom property declaration for a module token, using the provided fallback value.
+/// Creates a CSS custom property reference for a module token, using the provided fallback value.
 /// 
-@function _create-var($module, $token, $value, $prefix: config.$prefix) {
+@function create-var($module, $token, $value: null, $prefix: config.$prefix) {
+  @if $value == null {
+    @return var(--#{$prefix}-#{$module}-#{$token});
+  }
   @return var(--#{$prefix}-#{$module}-#{$token}, $value);
 }
 
+///
+/// Rounds a number to the specified number of decimal places.
+///
+@function round($value, $fractionDigits: 0) {
+  $power: math.pow(10, $fractionDigits);
+  @return math.div(math.round($power * $value), $power);
+}
+
+///
+/// Creates a CSS custom property declaration for a module token. 
+///
+@mixin declare-var($module, $name, $value, $prefix: config.$prefix) {
+  --#{$prefix}-#{$module}-#{$name}: #{$value};
+}
+
+///
+/// Declares an internal token reference variable for a module.
+/// 
+/// Example:
+/// ```sass
+/// #{create-module-var(color)}: red; // => --_component-name-color: red;
+/// ```
+/// 
+/// @param {String} $token - The token name.
+/// 
+@function create-module-var($module, $token) {
+  @return --_#{$module}-#{$token};
+}
+
+///
+/// Flattens multiple maps into a single map. 
+///
+@function flatten($maps...) {
+  $merged: ();
+  @each $map in $maps {
+    $merged: map.merge($merged, $map);
+  }
+  @return $merged;
+}

package/styles/core/styles/scrollbar/index.scss

@@ -0,0 +1,45 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use '../tokens/scrollbar/tokens';
+
+///
+/// Provides scrollbar styles.
+///
+@mixin base {
+  &::-webkit-scrollbar {
+    height: #{tokens.get(height)};
+    width: #{tokens.get(width)};
+  }
+  
+  &::-webkit-scrollbar-track {
+    background-color: #{tokens.get(track-container)};
+    
+    &:hover {
+      background-color: #{tokens.get(track-container-hover)};
+    }
+  }
+
+  &::-webkit-scrollbar-corner {
+    background-color: #{tokens.get(track-container)};
+  }
+
+  &::-webkit-scrollbar-thumb {
+    height: #{tokens.get(thumb-min-height)};
+    width: #{tokens.get(thumb-min-width)};
+    
+    border-radius: #{tokens.get(border-radius)};
+    border-width: #{tokens.get(border-width)};
+    border-style: solid;
+    border-color: transparent;
+    
+    background-color: #{tokens.get(thumb-container)};
+    background-clip: content-box;
+
+    &:hover {
+      background-color: #{tokens.get(thumb-container-hover)};
+    }
+  }
+}

package/styles/core/styles/spacing/index.scss

@@ -8,13 +8,20 @@
 @use '../tokens/spacing/tokens';
 @use '../utils';
 
+///
+/// Gets a spacing token value.
+/// 
+@function value($key) {
+  @return tokens.get($key);
+}
+
 ///
 /// Gets a CSS custom property declaration for a specific spacing token with its token value as the fallback value.
 /// 
 /// Example:
 /// ```scss
 /// .my-class {
-///   margin: spacing.variable('200'); // => margin: var(--forge-spacing-standard, 16px);
+///   margin: spacing.variable('100'); // => margin: var(--forge-spacing-standard, 16px);
 /// }
 /// ```
 /// 

package/styles/core/styles/theme/_color-utils.scss

@@ -0,0 +1,63 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use 'sass:meta';
+@use 'sass:math';
+@use 'sass:color';
+
+@function _linear-channel-value($channel-value) {
+  $normalized-channel-value: math.div($channel-value, 255);
+  @if $normalized-channel-value < 0.03928 {
+    @return math.div($normalized-channel-value, 12.92);
+  }
+
+  @return math.pow(math.div($normalized-channel-value + 0.055, 1.055), 2.4);
+}
+
+// Calculate the luminance for a color.
+// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
+@function luminance($color) {
+  $red: _linear-channel-value(color.red($color));
+  $green: _linear-channel-value(color.green($color));
+  $blue: _linear-channel-value(color.blue($color));
+
+  @return 0.2126 * $red + 0.7152 * $green + 0.0722 * $blue;
+}
+
+// Calculate the contrast ratio between two colors.
+// See https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests
+@function contrast-ratio($back, $front) {
+  $backLum: luminance($back) + 0.05;
+  $foreLum: luminance($front) + 0.05;
+  @return math.div(math.max($backLum, $foreLum), math.min($backLum, $foreLum));
+}
+
+// Determine whether the color is 'light' or 'dark'.
+@function tone($color) {
+  @if $color == 'dark' or $color == 'light' {
+    @return $color;
+  }
+
+  @if meta.type-of($color) != 'color' {
+    @warn '#{$color} is not a color. Falling back to "dark" tone.';
+    @return 'dark';
+  }
+
+  $minimumContrast: 3.1;
+  $lightContrast: contrast-ratio($color, white);
+  $darkContrast: contrast-ratio($color, rgba(black, 0.87));
+
+  @if ($lightContrast < $minimumContrast) and ($darkContrast > $lightContrast) {
+    @return 'light';
+  } @else {
+    @return 'dark';
+  }
+}
+
+// Determine whether to use dark or light text on top of given color to meet accessibility standards for contrast.
+// Returns 'dark' if the given color is light and 'light' if the given color is dark.
+@function contrast-tone($color) {
+  @return if(tone($color) == 'dark', 'light', 'dark');
+}

package/styles/core/styles/theme/_utils.scss

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use 'sass:meta';
+@use 'sass:string';
+@use 'sass:color';
+@use '../utils';
+@use './color-utils';
+
+///
+/// Returns a new color with the same hue and saturation as the input color, but with a different lightness value.
+/// 
+/// Example:
+/// scale(#ff0000, 50%) => #ff6060
+/// 
+/// @param {Color} $color - The input color.
+/// @param {Number} $lightness - The desired lightness percentage to scale `$color` by. Specified as a percentage number between 0 and 100.
+/// @return {Color} - The new color with the same hue and saturation as the input color, but with a different lightness value.
+///
+@function scale($color, $lightness) {
+  @return color.scale($color, $lightness: 100 - $lightness);
+}
+
+///
+/// Creates a new color by applying the specified emphasis to the input color via the alpha channel.
+/// 
+/// Example:
+/// emphasized(#ff0000, 50%) => rgba(255, 0, 0, 0.5)
+/// 
+/// @param {Color} $color - The input color.
+/// @param {Number} $alpha - The desired opacity to apply to `$color`.
+/// @return {Color} - The input color, but with an alpha channel value in `rgba()` format.
+/// 
+@function emphasized($color, $emphasis) {
+  @return rgba($color, $emphasis);
+}
+
+///
+/// Computes the contrast color for the provided color.
+/// 
+/// Example:
+/// contrast(#ff0000) => #ffffff
+/// 
+/// @param {Color} $color - The input color.
+/// @param {Color} $light - The light color to use for contrast. Default to `#ffffff`.
+/// @param {Color} $dark - The dark color to use for contrast. Default to `#000000`.
+/// @return {Color} - The contrast color for the provided color.
+/// 
+@function contrast($color, $alpha: null, $light: #ffffff, $dark: #000000) {
+  $contrast-color: if(color-utils.contrast-tone($color) == 'dark', $dark, $light);
+  @if $alpha != null {
+    @return emphasized($contrast-color, $alpha);
+  }
+  @return $contrast-color;
+}
+
+///
+/// Converts a color with an opacity value on top of a specific background color to an opaque hex color.
+/// 
+@function hexify($color, $background, $alpha: 100%) {
+  @return if($alpha == 100%, color.mix($background, $color, $alpha), color.mix($background, $color, 100 - $alpha));
+}
+
+///
+/// Determines if the provided value is a `color` type or not.
+/// 
+@function is-color($value) {
+  @return meta.type-of($value) == color;
+}
+
+///
+/// Computes the hue, saturation, lightness (and optionally alpha) values for the provided color and returns a string in HSL format.
+///
+@function hsl-values($color, $with-alpha: false) {
+  $value: utils.round(hue($color), 2) utils.round(saturation($color), 2) utils.round(lightness($color), 2);
+  @if ($with-alpha) {
+    $value: string.unquote($value + ' / ' + alpha($color));
+  }
+  @return $value;
+}

package/styles/core/styles/theme/index.scss

@@ -4,27 +4,18 @@
  * License: Apache-2.0
  */
 @use 'sass:map';
+@use 'sass:math';
 @use '../core/config';
 @use '../tokens/theme/tokens';
+@use '../tokens/theme/color-emphasis';
 @use '../utils';
 
 ///
 /// Emits custom property declarations for all default theme tokens.
 /// 
 @mixin properties {
-  /// Temporary tokens to map the MDC theme to Forge theme
-  /// TODO: Remove this once MDC dependency is removed
-  :root {
-    @each $token-name, $token-value in tokens.$mdc-remap {
-      --mdc-theme-#{$token-name}: #{$token-value};
-    }
-  }
-
-  // Forge theme tokens
-  :root {
-    @each $token-name, $token-value in tokens.$tokens {
-      --#{config.$prefix}-theme-#{$token-name}: #{$token-value};
-    }
+  @each $token-name, $token-value in tokens.$tokens {
+    --#{config.$prefix}-theme-#{$token-name}: #{$token-value};
   }
 }
 
@@ -37,6 +28,31 @@
   }
 }
 
+///
+/// Temporary tokens to map the MDC theme to Forge theme
+/// 
+/// TODO: Remove this once MDC dependency is removed
+/// 
+@mixin properties-compat {
+  @each $token-name, $token-value in tokens.$mdc-remap {
+    --mdc-theme-#{$token-name}: #{$token-value};
+  }
+}
+
+///
+/// Generates utility classes for each theme token as both `color` and `background-color` styles separately.
+/// 
+@mixin classes {
+  @each $token, $value in tokens.$tokens {
+    .#{config.$prefix}-color--#{$token} {
+      color: #{variable($token)};
+    }
+    .#{config.$prefix}-background--#{$token} {
+      background-color: #{variable($token)};
+    }
+  }
+}
+
 ///
 /// Gets a CSS custom property declaration for a specific theme token, with its token value as the fallback value
 /// 
@@ -50,3 +66,13 @@
 @mixin provide($tokens, $prefix: config.$prefix) {
   @include utils.provide(tokens.$tokens, $tokens, theme, $prefix);
 }
+
+///
+/// Gets a theme emphasis value by semantic name.
+/// 
+/// Valid names are `highest`, `higher`, `high`, `medium-high`, `medium`, `medium-low`, `low`, `lower`, and `lowest`.
+/// 
+@function emphasis($emphasis) {
+  @return math.div(color-emphasis.value($emphasis), 100%);
+}
+

package/styles/core/styles/tokens/_token-utils.scss

@@ -0,0 +1,118 @@
+/**
+ * @license
+ * Copyright 2023 Tyler Technologies, Inc. 
+ * License: Apache-2.0
+ */
+@use 'sass:meta';
+@use 'sass:map';
+@use 'sass:list';
+@use '../utils';
+
+///
+/// Mixin for providing theme tokens to the module using external names.
+/// 
+/// Example:
+/// ```sass
+/// provide-theme(( color: red )); // => --forge-component-name-color: red;
+/// ```
+/// 
+/// @param {String} $module - The module name.
+/// @param {Map} $tokens - The tokens for this module.
+/// @param {Map} $theme - The theme tokens. 
+///
+@mixin provide-theme($module, $tokens, $theme) {
+  @include utils.provide($tokens, $theme, $module);
+}
+
+///
+/// Creates an internal token reference variable for the module.
+///
+/// This function requires that the token exists in the module.
+/// 
+/// Example:
+/// ```sass
+/// color: #{token(color)}; // => color: var(--_component-name-color);
+/// color: #{token(my-color, custom)}; // => color: var(--_component-name-my-color);
+/// ```
+/// 
+/// @param {String} $module - The module name. 
+/// @param {String} $tokens - The tokens for this module.
+/// @param {String} $token - The token name.
+/// @param {String} $type - The type of token this is. Valid values are `token` and `custom`. Using `custom` will not check if the token exists.
+///
+@function token($module, $tokens, $token, $type: token) {
+  @if ($type == 'token' and not map.has-key($tokens, $token)) {
+    @error 'Invalid token "#{$token}" for module "#{$module}"';
+  }
+  @return utils.module-var($module, $token);
+}
+
+///
+/// Declares an internal token reference variable for the module.
+/// 
+/// Example:
+/// ```sass
+/// #{declare(color)}: red; // => --_component-name-color: red;
+/// ```
+/// 
+/// @param {String} $module - The module name. 
+/// @param {String} $token - The token name.
+/// 
+@function declare($module, $token) {
+  @return utils.create-module-var($module, $token);
+}
+
+///
+/// Creates a token CSS custom property definition to point one token to another.
+/// 
+/// If `$new-token` is not a valid token then the provided value will be used verbatim.
+/// 
+/// Example:
+/// ```sass
+/// #{override(color, new-color)}; // => --_component-name-color: var(--_component-name-new-color);
+/// ```
+///
+/// @param {String} $module - The module name.
+/// @param {String} $tokens - The tokens for this module.
+/// @param {String} $token - The token name to override.
+/// @param {String} $token-or-value - The token name (if exists) or value to point to.
+/// @param {Boolean} $type - The type of token this is. Valid values are `token` and `value`.
+/// 
+@mixin override($module, $tokens, $token, $token-or-value, $type: token) {
+  @include utils.override($module, $tokens, $token, $token-or-value, $type);
+}
+
+///
+/// Generates CSS custom property declarations for all provided module-level tokens.
+///
+/// @param {String} $module - The module name.
+/// @param {String} $tokens - The tokens for this module.
+/// @param {List} $includes - An optional list of token names to include from `$tokens`
+/// @param {List} $excludes - An optional list of token names to exclude from `$tokens`
+/// 
+@mixin tokens($module, $tokens, $includes: null, $excludes: null) {
+  @if ($includes) {
+    // We are including only specific tokens
+    @each $token in $includes {
+      @if (not map.has-key($tokens, $token)) {
+        @error 'Invalid include token "#{$token}" for module "#{$module}"';
+      }
+      #{declare($module, $token)}: #{map.get($tokens, $token)};
+    }
+  } @else {
+    // We are including all tokens, but first we need to check if any excluded tokens were provided
+    @if ($excludes) {
+      @each $token in $excludes {
+        @if (not map.has-key($tokens, $token)) {
+          @error 'Invalid exclude token "#{$token}" for module "#{$module}"';
+        }
+        $tokens: map.remove($tokens, $token);
+      }
+    }
+
+    @each $token-name, $token-value in $tokens {
+      #{declare($module, $token-name)}: #{$token-value};
+    }
+  }
+}
+