@tylertech/forge 3.0.0-next.22 → 3.0.0-next.24

package/styles/theme/_custom-properties.scss

@@ -1,311 +0,0 @@
-/**
- * @license
- * Copyright 2023 Tyler Technologies, Inc. 
- * License: Apache-2.0
- */
-@use 'sass:list';
-@use 'sass:map';
-@use 'sass:meta';
-@use 'sass:string';
-@use '@material/theme/css';
-
-/// Configuration for custom properties.
-/// @see {mixin} configure
-$_config: (
-  emit-custom-properties: true,
-  emit-fallback-values: true,
-  emit-fallback-vars: true,
-);
-
-/// Configure options for custom properties. The configuration will be applied
-/// within the scope of the mixin's content and reset when the mixin scope ends.
-///
-/// @example - scss
-///   @include configure($emit-fallback-values: false) {
-///     // No fallback values will be emitted within this mixin scope
-///     @include another-mixin();
-///   }
-///
-/// All parameters must be provided as argument lists.
-///
-/// @link https://sass-lang.com/documentation/values/lists#argument-lists
-///
-/// @param {Bool} $emit-custom-properties [true] - Enable or disable all
-///     custom property emission.
-/// @param {Bool} $emit-fallback-values [true] - Enable or disable emission of
-///     fallback CSS static values. This does not include dynamic `var()`
-///     fallback values.
-/// @param {Bool} $emit-fallback-vars [true] - Enable or disable emission of
-///     fallback `var()` values.
-@mixin configure($config...) {
-  @if not meta.content-exists() {
-    @error 'content is required for configure()';
-  }
-
-  $config: meta.keywords($config);
-  @each $key, $value in $config {
-    @if $value == null {
-      $config: map.remove($config, $key);
-    }
-  }
-
-  @if list.length($config) == 0 {
-    @content;
-  } @else {
-    $previous: $_config;
-    // Use !global to avoid shadowing
-    // https://sass-lang.com/documentation/variables#shadowing
-    $_config: map.merge($_config, $config) !global;
-    @content;
-    $_config: $previous !global;
-  }
-}
-
-/// Returns true if the parameter is a custom property Map.
-///
-/// @param {*} $value - the value to test.
-/// @return true if the value is a custom property Map, or false if not.
-@function is-custom-prop($value) {
-  @return meta.type-of($value) == 'map' and map.has-key($value, 'varname');
-}
-
-/// Indicates whether or not a value is a custom property var() string.
-///
-/// @example - scss
-///   $is-prop-string: is-custom-prop-string('var(--foo)'); // true
-///
-/// @param {*} $value - The value to test.
-/// @return {Bool} True if the value is a custom property var() string, or
-///     false if not.
-@function is-custom-prop-string($value) {
-  @return meta.type-of($value) == 'string' and string.slice($value, 1, 4) == 'var(';
-}
-
-/// Returns true if $prop1's varname and fallback values are deeply equal to
-/// $prop2's varname and fallback values.
-///
-/// @param {Map} $prop1 - the first value to test.
-/// @param {Map} $prop2 - the second value to test.
-/// @return true if both properties are deeply equal
-@function are-equal($prop1, $prop2) {
-  @return create-var($prop1) == create-var($prop2);
-}
-
-/// Creates a custom property Map.
-///
-/// @param {String} $varname - the custom property name.
-/// @param {String | Number | Map} - the fallback value (may be another custom
-///     property Map). May be null.
-/// @return a custom property Map.
-@function create($varname, $fallback: null) {
-  @if string.slice($varname, 1, 2) != '--' {
-    $varname: create-varname($varname);
-  }
-
-  @return (varname: $varname, fallback: $fallback);
-}
-
-/// Global prefix for all custom properties.
-$_varname-prefix: 'forge';
-
-/// Create a custom property variable name with the global prefix.
-///
-/// @example - scss
-///   $varname: create-varname(foo); // --forge-foo
-///
-/// @param {String} $name - The name of the custom property.
-/// @return {String} The full CSS custom property variable name.
-@function create-varname($name) {
-  @return --#{$_varname-prefix}-#{$name};
-}
-
-/// Returns the custom property variable name of a custom property Map.
-///
-/// @param {Map} $custom-prop - a custom property Map.
-/// @return the custom property variable name defined by the Map.
-@function get-varname($custom-prop) {
-  @return map.get($custom-prop, 'varname');
-}
-
-/// Returns the fallback value of a custom property Map. May be null if the
-/// custom property does not have a fallback.
-///
-/// @param {Map} $custom-prop - a custom property Map.
-/// @param {Bool} $shallow - if true, return the first fallback value, which
-///     may be another custom property Map. Defaults to false, which will return
-///     the deep final fallback value.
-/// @return the fallback value of a custom property Map. May be null.
-@function get-fallback($custom-prop, $shallow: false) {
-  $fallback: map.get($custom-prop, 'fallback');
-  @if is-custom-prop($fallback) and not $shallow {
-    @return get-fallback($fallback);
-  }
-
-  @return $fallback;
-}
-
-/// Creates a new custom property Map and returns it with the specified new
-/// fallback value.
-///
-/// @param {Map} $custom-prop - the custom property Map to copy.
-/// @param {String | Number | Map} $new-fallback - the new fallback value of the
-///     custom property Map. May be null.
-/// @param {Bool} $shallow - if true, set the first fallback value. Defaults to
-///     false, which will set the deep final fallback value.
-/// @return a new custom property Map with the new fallback value.
-@function set-fallback($custom-prop, $new-fallback, $shallow: false) {
-  $varname: get-varname($custom-prop);
-  $first-fallback: get-fallback($custom-prop, $shallow: true);
-
-  @if is-custom-prop($first-fallback) and not $shallow {
-    // The first fallback is a custom property and $shallow is false. Deeply
-    // set the fallback value of the custom property and get the new custom
-    // property Map returned.
-    $new-fallback: set-fallback($first-fallback, $new-fallback);
-  }
-
-  @return create($varname, $new-fallback);
-}
-
-/// Creates and returns a CSS `var()` function value represented by the provided
-/// custom property Map.
-///
-/// If custom properties are disabled, this function will return the custom
-/// property's fallback value instead, which may be `null` and result in an
-/// empty declaration.
-///
-/// @param {Map} $custom-prop - A custom property Map.
-/// @return {*} A CSS value, typically a `var()` function, representing the
-///     custom property. The returned value may change depending on the current
-///     configuration options for custom properties and whether or not a
-///     fallback value is present in the custom property Map.
-@function create-var($custom-prop) {
-  @if not map.get($_config, emit-custom-properties) {
-    // If configured not to emit custom properties and a request is made for a
-    // custom prop's CSS value, return its fallback value. If this is null, it
-    // will result in an empty declaration.
-    @return get-fallback($custom-prop);
-  }
-
-  $varname: get-varname($custom-prop);
-  $fallback: get-fallback($custom-prop, $shallow: true);
-
-  $emit-fallback-vars: map.get($_config, emit-fallback-vars);
-  $fallback-is-prop: is-custom-prop($fallback);
-  @if $fallback-is-prop and $emit-fallback-vars {
-    @return var($varname, create-var($fallback));
-  }
-
-  $emit-fallback-values: map.get($_config, emit-fallback-values);
-  @if $fallback and not $fallback-is-prop and $emit-fallback-values {
-    @return var($varname, $fallback);
-  }
-
-  @return var($varname);
-}
-
-/// Retrieves the CSS declaration value for a custom property Map. This is
-/// typically a `var()` function.
-///
-/// If custom properties are disabled, the custom property's fallback value
-/// will be returned instead. If the fallback value is `null`, an error will
-/// be thrown.
-///
-/// @param {Map} $custom-prop - The custom property Map to retrieve a
-///     declaration value for.
-/// @return {*} The CSS declaration value.
-@function get-declaration-value($custom-prop) {
-  $emit-custom-properties: map.get($_config, emit-custom-properties);
-  $fallback: get-fallback($custom-prop);
-  @if not $emit-custom-properties and not $fallback {
-    @error 'Custom properties are disabled and #{get-varname($custom-prop)} does not have a fallback value.';
-  }
-
-  @if not $emit-custom-properties {
-    @return $fallback;
-  }
-
-  @return create-var($custom-prop);
-}
-
-/// Retrieves the CSS fallback declaration value for a custom property Map.
-/// This is typically a static CSS value if a custom property has a fallback, or
-/// null if it does not.
-///
-/// This function will always return `null` if custom properties or fallback
-/// values are disabled.
-///
-/// @param {Map} $custom-prop - The custom property Map to retrieve a fallback
-///     declaration value for.
-/// @return {String | null} The CSS fallback declaration value.
-@function get-declaration-fallback($custom-prop) {
-  $emit-custom-properties: map.get($_config, emit-custom-properties);
-  $emit-fallback-values: map.get($_config, emit-fallback-values);
-  @if not $emit-custom-properties or not $emit-fallback-values {
-    @return null;
-  }
-
-  @return get-fallback($custom-prop);
-}
-
-/// Emits a CSS declaration for a custom property. A custom property may either
-/// be provided as the value to a CSS property string to be emitted as a var()
-/// function, or as a standalone value to be emitted as a custom property
-/// declaration.
-///
-/// @example - scss
-///   @include declaration(color, create(--foo, teal));
-///   // color: var(--foo, teal);
-///   @include declaration(create(--foo, teal));
-///   // --foo: teal;
-///
-/// Standalone custom properties must have a fallback value to emit as a CSS
-/// declaration.
-///
-/// The declaration emitted for a custom property may change or be ignored
-/// based on the current configuration for custom properties.
-///
-/// @see {mixin} css.declaration
-/// @see {mixin} configuration
-///
-/// @param {String} $property - The CSS property of the declaration or the
-///     custom property Map to emit.
-/// @param {Map} $custom-prop - A custom property Map for the property's value.
-///     Optional if $property is the custom property Map to emit.
-/// @param {Map} $gss - An optional Map of GSS annotations to add.
-/// @param {Bool} $important - If true, add `!important` to the declaration.
-@mixin declaration($property, $custom-prop: null, $gss: (), $important: false) {
-  @if $property {
-    $value: null;
-    $fallback-value: null;
-    @if is-custom-prop($property) {
-      @if map.get($_config, emit-custom-properties) {
-        $custom-prop: $property;
-        $property: get-varname($custom-prop);
-        $value: get-fallback($custom-prop, $shallow: true);
-        @if not $value {
-          @error 'Custom property #{get-varname($property)} does not have a fallback value to emit for a CSS declaration.';
-        }
-
-        @if is-custom-prop($value) {
-          $value: create-var($value);
-        }
-      }
-    } @else {
-      @if not is-custom-prop($custom-prop) {
-        @error "Invalid custom property: #{$custom-prop}. Must be a Map with 'varname' and 'fallback'.";
-      }
-
-      $value: get-declaration-value($custom-prop);
-      $fallback-value: get-declaration-fallback($custom-prop);
-    }
-
-    @include css.declaration(
-      $property,
-      $value,
-      $fallback-value: $fallback-value,
-      $gss: $gss,
-      $important: $important
-    );
-  }
-}