@material/web 0.1.0-alpha.0

package/compat/theme/_theme-color.scss

@@ -0,0 +1,344 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:color';
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:math';
+@use 'sass:meta';
+@use 'sass:string';
+@use './custom-properties';
+@use './keys';
+
+@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($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($color, white);
+  $darkContrast: contrast($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');
+}
+
+///
+/// @param $color Target color in any color format.
+/// @return Returns hash in string format that uniquely represents
+///     any given color format. Useful for generating unique keyframe names.
+/// @example
+///   `color-hash(#6200ee)` => "6200ee"
+///   `color-hash(rgb(255, 112, 112))` => "ff7070"
+///   `color-hash((varname: --my-fancy-color, fallback: teal))` => 'teal'
+///   `color-hash((varname: --my-fancy-color, fallback: null))` => '--my-fancy-color'
+///
+@function color-hash($color) {
+  @if custom-properties.is-custom-prop($color) {
+    $color-value: custom-properties.get-fallback($color);
+
+    @if (custom-properties.is-custom-prop-string($color-value)) {
+      $varEndIndex: if(
+        string.index($color-value, ', '),
+        string.index($color-value, ', ') - 1,
+        -2
+      );
+      @return string.slice($color-value, 5, $varEndIndex);
+    }
+
+    @if (meta.type-of($color-value) == 'color') {
+      @return _get-hex-string($color-value);
+    }
+
+    @return custom-properties.get-varname($color);
+  }
+
+  @if meta.type-of($color) == 'string' {
+    @return $color;
+  }
+
+  @return _get-hex-string($color);
+}
+
+@function _get-hex-string($color) {
+  @return string.slice(color.ie-hex-str($color), 2); // Index starts at 1
+}
+
+//
+// Main theme colors for your brand.
+//
+// If you're a user customizing your color scheme in SASS, these are probably the only variables you need to change.
+//
+
+$primary: #6200ee !default; // baseline purple, 500 tone
+$on-primary: if(contrast-tone($primary) == 'dark', #000, #fff) !default;
+
+// The $mdc-theme-accent variable is DEPRECATED - it exists purely for backward compatibility.
+// The $mdc-theme-secondary* variables should be used for all new projects.
+/// @deprecated - use $secondary
+$accent: #018786 !default; // baseline teal, 600 tone
+$secondary: $accent !default;
+$on-secondary: if(contrast-tone($secondary) == 'dark', #000, #fff) !default;
+$background: #fff !default; // White
+
+$surface: #fff !default;
+$on-surface: if(contrast-tone($surface) == 'dark', #000, #fff) !default;
+
+$error: #b00020 !default;
+$on-error: if(contrast-tone($error) == 'dark', #000, #fff) !default;
+
+//
+// Text colors according to light vs dark and text type.
+//
+
+$text-colors: (
+  dark: (
+    primary: rgba(black, 0.87),
+    secondary: rgba(black, 0.54),
+    hint: rgba(black, 0.38),
+    disabled: rgba(black, 0.38),
+    icon: rgba(black, 0.38),
+  ),
+  light: (
+    primary: white,
+    secondary: rgba(white, 0.7),
+    hint: rgba(white, 0.5),
+    disabled: rgba(white, 0.5),
+    icon: rgba(white, 0.5),
+  ),
+) !default;
+
+$text-emphasis: (
+  high: 0.87,
+  medium: 0.6,
+  disabled: 0.38,
+) !default;
+
+@function ink-color-for-fill_($text-style, $fill-color) {
+  $contrast-tone: contrast-tone($fill-color);
+
+  @return map.get(map.get($text-colors, $contrast-tone), $text-style);
+}
+
+//
+// Primary text colors for each of the theme colors.
+//
+
+/// @deprecated Use individual variables (`$primary`, `$secondary`). Do not
+/// override this Map of variables.
+$property-values: (
+  primary: $primary,
+  secondary: $secondary,
+  background: $background,
+  surface: $surface,
+  error: $error,
+  on-primary: $on-primary,
+  on-secondary: $on-secondary,
+  on-surface: $on-surface,
+  on-error: $on-error,
+  text-primary-on-background: ink-color-for-fill_(primary, $background),
+  text-secondary-on-background: ink-color-for-fill_(secondary, $background),
+  text-hint-on-background: ink-color-for-fill_(hint, $background),
+  text-disabled-on-background: ink-color-for-fill_(disabled, $background),
+  text-icon-on-background: ink-color-for-fill_(icon, $background),
+  text-primary-on-light: ink-color-for-fill_(primary, light),
+  text-secondary-on-light: ink-color-for-fill_(secondary, light),
+  text-hint-on-light: ink-color-for-fill_(hint, light),
+  text-disabled-on-light: ink-color-for-fill_(disabled, light),
+  text-icon-on-light: ink-color-for-fill_(icon, light),
+  text-primary-on-dark: ink-color-for-fill_(primary, dark),
+  text-secondary-on-dark: ink-color-for-fill_(secondary, dark),
+  text-hint-on-dark: ink-color-for-fill_(hint, dark),
+  text-disabled-on-dark: ink-color-for-fill_(disabled, dark),
+  text-icon-on-dark: ink-color-for-fill_(icon, dark),
+) !default;
+
+@include keys.set-values(
+  $property-values,
+  $options: (custom-property-prefix: theme)
+);
+
+// A copy of the property values Map that is used to detect compile-time changes
+// for Angular support.
+$_property-values-copy: $property-values;
+
+/// Checks if the global $mdc-theme-property-values was dynamically changed at
+/// compile time. Typically, $property-values is configured once, but a Sass
+/// hack allows the variable to be changed multiple times and effectively
+/// support dynamic values.
+///
+/// Angular uses this in their dynamic theming. This function checks if this
+/// scenario has occurred and returns the current global value that should be
+/// used instead of the key store value.
+///
+/// @deprecated The function should not be used externally. It will be removed
+///     when $mdc-theme-property-values is fully deprecated and removed.
+@function deprecated-get-global-theme-key-value-if-changed($key) {
+  // Determine if we need to use a compile-time updated value to support
+  // Angular.
+  $current-global-value: map.get($property-values, $key);
+  $configured-global-value: map.get($_property-values-copy, $key);
+  @if $current-global-value != $configured-global-value {
+    // $mdc-theme-property-values was changed at compile time. Return the new
+    // compile-time value.
+    @return (value: $current-global-value, changed: true);
+  }
+
+  @return (changed: false);
+}
+
+// @deprecated use theme.property(). If you need to ensure the value is not a
+// custom property, use custom-properties.is-custom-prop() to check if the value
+// is a custom prop, then custom-properties.get-fallback() to get its value.
+// If `$style` is a color (a literal color value, `currentColor`, or a CSS custom property), it is returned verbatim.
+// Otherwise, `$style` is treated as a theme property name, and the corresponding value from
+// `$mdc-theme-property-values` is returned. If this also fails, an error is thrown.
+//
+// This is mainly useful in situations where `mdc-theme-prop` cannot be used directly (e.g., `box-shadow`).
+//
+// Examples:
+//
+// 1. mdc-theme-prop-value(primary) => "#6200ee"
+// 2. mdc-theme-prop-value(blue)    => 'blue'
+//
+// NOTE: This function must be defined in _variables.scss instead of _functions.scss to avoid circular imports.
+@function prop-value($style) {
+  @if custom-properties.is-custom-prop($style) {
+    @return custom-properties.get-fallback($style);
+  }
+
+  @if is-valid-theme-prop-value_($style) {
+    @return $style;
+  }
+
+  @if is-theme-key($style) {
+    // Determine if we need to use a compile-time updated value to support
+    // Angular.
+    $result: deprecated-get-global-theme-key-value-if-changed($style);
+    @if map.get($result, changed) {
+      @return map.get($result, value);
+    }
+  }
+
+  @return keys.resolve($style);
+}
+
+// NOTE: This function must be defined in _variables.scss instead of _functions.scss to avoid circular imports.
+@function accessible-ink-color($fill-color, $text-style: primary) {
+  $fill-color-value: prop-value($fill-color);
+  $color-map-for-tone: map.get($text-colors, contrast-tone($fill-color-value));
+
+  @if not map.has-key($color-map-for-tone, $text-style) {
+    @error "Invalid $text-style: '#{$text-style}'. Choose one of: #{map.keys($color-map-for-tone)}";
+  }
+
+  @return map.get($color-map-for-tone, $text-style);
+}
+
+// NOTE: This function is depended upon by mdc-theme-prop-value (above) and thus must be defined in this file.
+@function is-valid-theme-prop-value_($style) {
+  @return meta.type-of($style) == 'color' or $style == 'currentColor' or
+    str_slice($style, 1, 4) == 'var(' or $style == 'inherit' or $style ==
+    'transparent' or
+    // NOTE: `GrayText` is deprecated, but is the only feasible way to convey the
+    // correct high-contrast mode colors in alignment with Windows system colors.
+    $style == 'GrayText';
+}
+
+@function text-emphasis($emphasis) {
+  @return map.get($text-emphasis, $emphasis);
+}
+
+@function is-theme-key($style) {
+  @return map.has-key($property-values, $style);
+}
+
+@function get-theme-keys() {
+  @return map.keys($property-values);
+}
+
+///
+/// @param {Color|String} Color property key name (i.e., `primary`, `secondary`,
+///     etc).
+/// @return Returns custom property map containing CSS custom property and
+///     fallback value (i.e., (varname: ..., fallback: ...). Returns color if
+///     valid color value is provided. Throws error otherwise.
+/// @examples
+///   1. get-custom-property(primary)
+///   => (varname: --mdc-theme-primary, fallback: #6200ee)
+///
+///   2. get-custom-property(#fff)
+///   => #fff
+///
+@function get-custom-property($color) {
+  $is-tokens-custom-prop: meta.type-of($color) == 'string' and
+    string.index($color, '--') != null;
+  @if custom-properties.is-custom-prop($color) or
+    $is-tokens-custom-prop or
+    is-valid-theme-prop-value_($color)
+  {
+    @return $color;
+  } @else if is-theme-key($color) {
+    $custom-prop: keys.create-custom-property($color);
+
+    // Determine if we need to use a compile-time updated value to support
+    // Angular.
+    $result: deprecated-get-global-theme-key-value-if-changed($color);
+    @if map.get($result, changed) {
+      $custom-prop: custom-properties.set-fallback(
+        $custom-prop,
+        map.get($result, value)
+      );
+    }
+
+    @return $custom-prop;
+  } @else {
+    @error "Invalid theme property: '#{$color}'. Choose one of: #{get-theme-keys()}";
+  }
+}

package/compat/theme/_theme.scss

@@ -0,0 +1,334 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use './css';
+@use './custom-properties';
+@use './gss';
+@use './keys';
+@use './replace';
+@use './theme-color';
+
+@mixin core-styles($query: feature-targeting.all()) {
+  $feat-color: feature-targeting.create-target($query, color);
+
+  :root {
+    @include feature-targeting.targets($feat-color) {
+      @each $style in theme-color.get-theme-keys() {
+        @include custom-properties.declaration(
+          keys.create-custom-property($style)
+        );
+      }
+    }
+  }
+
+  @each $style in theme-color.get-theme-keys() {
+    @if $style != 'background' and $style != 'surface' {
+      .mdc-theme--#{$style} {
+        @include feature-targeting.targets($feat-color) {
+          @include property(color, $style, $important: true);
+        }
+      }
+    } @else {
+      .mdc-theme--#{$style} {
+        @include feature-targeting.targets($feat-color) {
+          @include property(background-color, $style);
+        }
+      }
+    }
+  }
+
+  // CSS rules for using primary and secondary (plus light/dark variants) as background colors.
+  @each $style in ('primary', 'secondary') {
+    .mdc-theme--#{$style}-bg {
+      @include feature-targeting.targets($feat-color) {
+        @include property(background-color, $style, $important: true);
+      }
+    }
+  }
+}
+
+/// Applies a dynamic value to the specified property. This mixin should be used
+/// in theme style mixins when setting properties.
+///
+/// The value may be any of the following:
+/// - a standard CSS value
+/// - a custom property Map, e.g. (varname: --mdc-foo, fallback: blue)
+/// - a Material theme key String, e.g. 'primary', 'on-primary'
+///
+/// @example
+///   @include theme.property(color, teal);
+///   @include theme.property(color, custom-properties.create(foo, blue));
+///   @include theme.property(color, primary);
+///
+/// A `$replace` Map parameter may be provided to replace key/value pairs for
+/// string values. This can be used to substitute parameters in complex string
+/// values such as `calc()` with custom properties.
+///
+/// @example
+///   @include theme.property(
+///     width,
+///     calc(foo + bar),
+///     $replace: (foo: custom-properties.create(foo), bar: 8px)
+///   );
+///
+/// Note: Material theme key Strings (e.g. `primary`) are not supported as
+/// replacement values.
+///
+/// A CSS custom property declaration may be emitted by providing a custom
+/// property Map to `$property`. The fallback value (or `$value` if provided)
+/// will be used as the declaration value.
+///
+/// @example - scss
+///   .foo {
+///     @include theme.property(custom-properties.create(foo, teal));
+///     @include theme.property(custom-properties.create(bar, teal), blue);
+///   }
+///
+/// @example - css
+///   .foo {
+///     --mdc-foo: teal;
+///     --mdc-bar: blue;
+///   }
+///
+/// @param {String | Map} $property - The name of the CSS property. May also be
+///     a custom property Map to emit a custom propery declaration.
+/// @param {String | Number | Color | List | Map} $value - The property's value.
+///     This parameter may be omitted if `$property` is a custom property Map.
+/// @param {Map} $gss - Optional Map of GSS annotations to set.
+/// @param {Map} $replace - An optional Map of replacement key/value pairs if
+///     the `$value` is a string.
+/// @param {Bool} $important - Set to true to add an `!important` rule. Defaults
+///     to false.
+@mixin property(
+  $property,
+  $value: null,
+  $gss: (),
+  $replace: null,
+  $important: false
+) {
+  @if custom-properties.is-custom-prop($property) {
+    // $property is a custom property Map
+    //   --mdc-foo: value;
+    @if $value {
+      $property: custom-properties.set-fallback(
+        $property,
+        $value,
+        $shallow: true
+      );
+    }
+
+    @include custom-properties.declaration(
+      $property,
+      $gss: $gss,
+      $important: $important
+    );
+  } @else if custom-properties.is-custom-prop($value) {
+    // $value is a custom property Map
+    //   property: var(--mdc-foo, fallback);
+    @include custom-properties.declaration(
+      $property,
+      $value,
+      $gss: $gss,
+      $important: $important
+    );
+  } @else if keys.is-key($value) {
+    // $value is a key String
+    //   property: key;
+    $custom-prop: keys.create-custom-property($value);
+
+    @if theme-color.is-theme-key($value) {
+      // Determine if we need to use a compile-time updated value to support
+      // Angular.
+      $key: $value;
+      // (changed: Bool, value: *)
+      $result: theme-color.deprecated-get-global-theme-key-value-if-changed(
+        $key
+      );
+
+      @if map.get($result, changed) {
+        // $mdc-theme-property-values was changed at compile time. Use the
+        // global value instead. Otherwise if it was not changed, continue
+        // using the key store normally.
+        $custom-prop: keys.create-custom-property($key);
+        $custom-prop: custom-properties.set-fallback(
+          $custom-prop,
+          map.get($result, value)
+        );
+      }
+    }
+
+    @include custom-properties.declaration(
+      $property,
+      $custom-prop,
+      $gss: $gss,
+      $important: $important
+    );
+  } @else {
+    // $value is a standard CSS value
+    //   property: value;
+    $fallback: null;
+    @if $replace {
+      // If any replacements are null, treat the entire value as null (do not
+      // emit anything).
+      @each $name, $replacement in $replace {
+        @if $replacement == null {
+          $value: null;
+        }
+      }
+    }
+
+    @if $replace and $value {
+      @if meta.type-of($replace) != 'map' {
+        @error 'mdc-theme: Invalid replacement #{$replace}. Must be a Map.';
+      }
+
+      $replace-map-fallback: ();
+      $replace-map-value: ();
+      $needs-fallback: false;
+      @each $name, $replacement in $replace {
+        @if custom-properties.is-custom-prop($replacement) {
+          $replace-value: custom-properties.get-declaration-value($replacement);
+          $replace-fallback: custom-properties.get-declaration-fallback(
+            $replacement
+          );
+          @if $replace-fallback {
+            $needs-fallback: true;
+          }
+
+          $replace-map-value: map.set(
+            $replace-map-value,
+            $name,
+            $replace-value
+          );
+          $replace-map-fallback: map.set(
+            $replace-map-fallback,
+            $name,
+            $replace-fallback
+          );
+        } @else {
+          $replace-map-value: map.set($replace-map-value, $name, $replacement);
+          $replace-map-fallback: map.set(
+            $replace-map-fallback,
+            $name,
+            $replacement
+          );
+        }
+      }
+
+      @if meta.type-of($value) == 'string' {
+        @if $needs-fallback {
+          $fallback: replace.replace-string($value, $replace-map-fallback);
+        }
+        $value: replace.replace-string($value, $replace-map-value);
+      } @else if meta.type-of($value) == 'list' {
+        @if $needs-fallback {
+          $fallback: replace.replace-list($value, $replace-map-fallback);
+        }
+        $value: replace.replace-list($value, $replace-map-value);
+      } @else {
+        @error 'mdc-theme: Invalid replacement value #{$value}. $replace may only be used with string or list values.';
+      }
+    }
+
+    @include css.declaration(
+      $property,
+      $value,
+      $fallback-value: $fallback,
+      $gss: $gss,
+      $important: $important
+    );
+  }
+}
+
+// @deprecated use the `property()` mixin instead
+@mixin prop($property, $style, $important: false) {
+  @include property($property, $style, $important: $important);
+}
+
+/// Validates theme configuration keys by comparing it with original theme
+/// configuration, also validates theme values to see if it has any unsupported
+/// value formats.
+/// @param {Map} $origin-theme - Original theme configuration in Sass map format
+///     that has all supported keys.
+/// @param {Map} $custom-theme - Provided theme configuration in Sass map format
+///     that should be validated against `$origin-theme`.
+/// @examples
+///     @mixin theme($theme) {
+///       @include theme.validate-theme($light-theme, $theme);
+///
+///       // ...
+///     }
+@mixin validate-theme($origin-theme, $custom-theme, $test-only: false) {
+  @include validate-theme-keys(
+    $origin-theme,
+    $custom-theme,
+    $test-only: $test-only
+  );
+  @include _validate-theme-values($custom-theme, $test-only: $test-only);
+}
+
+/// Validates theme configuration keys by comparing it with original theme
+/// configuration.
+/// @see Use `validate-theme()` to validate both theme keys and theme values.
+/// @param {Map} $origin-theme - Original theme configuration in Sass map format
+///     that has all supported keys.
+/// @param {Map} $custom-theme - Provided theme configuration in Sass map format
+///     that should be validated against `$origin-theme`.
+@mixin validate-theme-keys($origin-theme, $custom-theme, $test-only: false) {
+  $origin-keys: map.keys($origin-theme);
+  $unsupported-keys: ();
+
+  @each $key, $value in $custom-theme {
+    @if (not list.index($origin-keys, $key)) {
+      $unsupported-keys: list.append(
+        $unsupported-keys,
+        $key,
+        $separator: comma
+      );
+    }
+  }
+
+  @if list.length($unsupported-keys) > 0 {
+    $error-message: 'Unsupported keys found: #{$unsupported-keys}. Expected one of: #{$origin-keys}.';
+
+    @if $test-only {
+      content: $error-message;
+    } @else {
+      @error $error-message;
+    }
+  }
+}
+
+/// Validates theme configuration values to see if it has any unsupported value
+/// formats.
+/// @see Use `validate-theme()` to validate both theme keys and theme values.
+/// @param {Map} $custom-theme - Provided theme configuration in Sass map format
+///     that needs to be validated.
+@mixin _validate-theme-values($custom-theme, $test-only: false) {
+  $unsupported-custom-prop-keys: ();
+
+  @each $key, $value in $custom-theme {
+    @if custom-properties.is-custom-prop($value) {
+      $unsupported-custom-prop-keys: list.append(
+        $unsupported-custom-prop-keys,
+        $key,
+        $separator: comma
+      );
+    }
+  }
+
+  @if list.length($unsupported-custom-prop-keys) > 0 {
+    $error-message: 'Custom properties are not supported for theme map keys: #{$unsupported-custom-prop-keys}';
+
+    @if $test-only {
+      content: $error-message;
+    } @else {
+      @error $error-message;
+    }
+  }
+}