@material/web 0.1.0-alpha.0

package/sass/_theme.scss

@@ -0,0 +1,245 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use './string-ext';
+@use './var';
+
+/// Transform a user-provided `$theme` map's values into `var()` custom property
+/// values.
+///
+/// Use this function in `theme-styles()` mixins to transform values into
+/// custom property `var()` "slots" that can subsequently be styled via
+/// `theme.emit-theme-vars()` in the `theme()` mixin by the user.
+///
+/// @example - scss
+///   $light-theme: (
+///     label-color: purple
+///   );
+///
+///   @mixin theme-styles($theme) {
+///     $theme: theme.create-theme-vars($theme, button);
+///
+///     .foo {
+///       color: map.get($theme, label-color);
+///     }
+///   }
+///
+/// @example - css
+///     .foo {
+///       color: var(--md-button-label-color, purple);
+///     }
+///
+/// @param {Map} $theme - The theme Map to transform values into custom property
+///     `var()`s.
+/// @param {String} $prefix - Component and variant prefix to prepend for each
+///     token's custom property name.
+/// @return {Map} The provided `$theme` Map whose values are replaced with the
+///     `var()` custom properties.
+@function create-theme-vars($theme, $prefix) {
+  @each $key, $value in $theme {
+    @if $value != null {
+      $token: combine-tokens($prefix, $key);
+
+      @if meta.type-of($value) == 'map' {
+        $value: create-theme-vars($value, $token);
+      } @else {
+        $value: var.create($token, $value);
+      }
+
+      $theme: map.set($theme, $key, $value);
+    }
+  }
+
+  @return $theme;
+}
+
+/// Emits CSS declaration values for a theme map that has been transformed with
+/// `create-theme-vars()`.
+///
+/// Use this in `theme()` mixins to set user-provided token customizations.
+///
+/// @example - scss
+///   $light-theme: (
+///     label-color: purple
+///   );
+///
+///   @mixin theme($theme) {
+///     $theme: theme.create-theme-vars($theme, button);
+///
+///     @include theme.emit-theme-vars($theme);
+///   }
+///
+///   .my-button {
+///     @include theme((label-color: teal));
+///   }
+///
+/// @example - css
+///   .my-button {
+///     --md-button-label-color: teal;
+///   }
+///
+/// @param {Map} $theme - The theme Map to emit custom property declarations
+///     for.
+@mixin emit-theme-vars($theme) {
+  @each $token, $value in $theme {
+    @if $value {
+      @if meta.type-of($value) == 'map' {
+        @include emit-theme-vars($value);
+      } @else if not var.is-var($value) {
+        @error '"#{$token}": #{$value} is not a var(). Call create-theme-vars($theme) before emit-theme-vars($theme).';
+      } @else {
+        #{var.name($value)}: #{var.fallback($value)};
+      }
+    }
+  }
+}
+
+/// Combines one or more token parts into a token.
+///
+/// @example - scss
+///   $key: combine(body, font-size);
+///   // body-font-size
+///
+/// @param {String...} $parts - Arbitrary number of string token parts to
+///     combine.
+/// @return {String} A combined token string.
+@function combine-tokens($parts...) {
+  // Allow extra keywords to be passed to other functions without impacting this
+  // function, which does not expect any keywords.
+  $unused: meta.keywords($parts);
+  $token: '';
+  @each $part in $parts {
+    @if $part {
+      @if $token == '' {
+        $token: $part;
+      } @else {
+        $token: #{$token}-#{$part};
+      }
+    }
+  }
+
+  @return $token;
+}
+
+/// Validates a theme's tokens and values and throws an error if incorrect
+/// tokens are present or invalid values are provided.
+///
+/// Use this in `theme()` mixins to validate user-provided `$theme` maps before
+/// providing the value to `theme.create-theme-vars()`.
+///
+/// @example - scss
+///   @mixin theme($theme) {
+///     $theme: theme.validate-theme($light-theme, $theme);
+///     $theme: theme.create-theme-vars($theme, checkbox);
+///   }
+///
+/// @throw If any tokens or values are invalid.
+/// @param {Map} $reference-theme - A reference theme Map whose token keys will
+///     be used to validate the user-provided theme.
+/// @param {Map} $theme - User-provided theme Map to validate.
+/// @return {Map} The validated user-provided theme Map.
+@function validate-theme($reference-theme, $theme) {
+  $theme: _validate-theme-tokens(
+    map.keys($reference-theme),
+    $theme,
+    $require-all: false
+  );
+
+  @return $theme;
+}
+
+/// Validates a theme's tokens and throws an error if incorrect tokens are
+/// present or any tokens are missing.
+///
+/// Use this in internal `theme-styles()` mixins to validate library-provided
+/// `$theme` maps and ensure that all tokens are correct and present.
+///
+/// @example - scss
+///   @mixin theme-styles($theme) {
+///     $theme: theme.validate-theme-styles($light-theme, $theme);
+///     $theme: theme.create-theme-vars($theme, checkbox);
+///   }
+///
+/// @throw If any tokens are invalid or missing.
+/// @param {Map|List} $reference-theme - A complete reference theme Map (or List
+///     of tokens) to validate the theme.
+/// @param {Map} $theme - The theme Map to validate.
+/// @return {Map} The validated theme Map.
+@function validate-theme-styles($reference-theme, $theme, $require-all: true) {
+  $valid-tokens: $reference-theme;
+  @if meta.type-of($reference-theme) == 'map' {
+    $valid-tokens: map.keys($reference-theme);
+  }
+
+  @return _validate-theme-tokens(
+    $valid-tokens,
+    $theme,
+    $require-all: $require-all
+  );
+}
+
+/// Validates a theme's tokens and throws an error if incorrect tokens are
+/// present or optionally missing if `$require-all` is true.
+///
+/// @throw If any tokens are invalid or optionally missing.
+/// @param {List} $valid-tokens - A List of token keys to validate the theme.
+/// @param {Map} $theme - The theme Map to validate.
+/// @param {Bool} $require-all [false] - If true, throw an error if the theme
+///     is missing tokens from the list.
+/// @return {Map} The validated theme Map.
+@function _validate-theme-tokens($valid-tokens, $theme, $require-all: false) {
+  $missing-tokens: ();
+  $unsupported-tokens: ();
+
+  @each $token, $value in $theme {
+    @if list.index($valid-tokens, $token) == null {
+      $unsupported-tokens: list.append(
+        $unsupported-tokens,
+        $token,
+        $separator: comma
+      );
+    }
+  }
+
+  @if $require-all {
+    // TODO(b/203778922): Remove when type composite tokens are removed
+    $ignore-suffix: (
+      // Ignore composite font tokens
+      '-type'
+    );
+
+    @each $token in $valid-tokens {
+      $missing: map.get($theme, $token) == null;
+      @if $missing {
+        @each $suffix in $ignore-suffix {
+          @if string-ext.has-suffix($token, $suffix) {
+            $missing: false;
+          }
+        }
+      }
+
+      @if $missing {
+        $missing-tokens: list.append(
+          $missing-tokens,
+          $token,
+          $separator: comma
+        );
+      }
+    }
+  }
+
+  @if list.length($unsupported-tokens) > 0 {
+    @error 'The following tokens are invalid: #{$unsupported-tokens}.';
+  }
+
+  @if list.length($missing-tokens) > 0 {
+    @error 'The following required tokens are missing: #{$missing-tokens}.';
+  }
+
+  @return $theme;
+}

package/sass/_touch-target.scss

@@ -0,0 +1,22 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+$_default-touch-target-height: 48px !default;
+$_default-touch-target-width: 48px !default;
+
+/// Styles applied to the component's inner touch target element.
+/// @param $height [$_default-touch-target-height] - Touch target height.
+/// @param $width [$_default-touch-target-width] - Touch target width.
+@mixin touch-target(
+  $height: $_default-touch-target-height,
+  $width: $_default-touch-target-width
+) {
+  position: absolute;
+  top: 50%;
+  height: $height;
+  left: 50%;
+  width: $width;
+  transform: translate(-50%, -50%);
+}

package/sass/_typography.scss

@@ -0,0 +1,114 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:map';
+@use 'sass:math';
+@use 'sass:meta';
+@use './theme';
+
+/// Resolves a theme's typography tokens for the given prefix.
+///
+/// @example - scss
+///   // $theme has the following tokens:
+///   // - label-text-font
+///   // - label-text-line-height
+///   // - label-text-size
+///   // - label-text-tracking
+///   // - label-text-weight
+///   $theme: resolve-theme($theme, map.get($resolvers, typography), label-text);
+///
+/// @param {Map} $theme - The theme to resolve tokens for.
+/// @param {Function} $resolver - The typography resolver to use.
+/// @param {String...} $token-prefixes - The prefix(es) of a typography token
+///     set.
+/// @return {Map} The theme with resolved typography tokens.
+@function resolve-theme($theme, $resolver, $token-prefixes...) {
+  @if $resolver == null {
+    @return $theme;
+  }
+
+  @each $token-prefix in $token-prefixes {
+    $typography-theme: meta.call(
+      $resolver,
+      $font: map.get($theme, '#{$token-prefix}-font'),
+      $line-height: map.get($theme, '#{$token-prefix}-line-height'),
+      $size: map.get($theme, '#{$token-prefix}-size'),
+      $tracking: map.get($theme, '#{$token-prefix}-tracking'),
+      $weight: map.get($theme, '#{$token-prefix}-weight')
+    );
+
+    $theme: map.merge(
+      $theme,
+      (
+        '#{$token-prefix}-font': map.get($typography-theme, font),
+        '#{$token-prefix}-line-height': map.get($typography-theme, line-height),
+        '#{$token-prefix}-size': map.get($typography-theme, size),
+        '#{$token-prefix}-tracking': map.get($typography-theme, tracking),
+        '#{$token-prefix}-weight': map.get($typography-theme, weight),
+      )
+    );
+  }
+
+  @return $theme;
+}
+
+/// Resolves typography tokens, converting `px` to `rem` where appropriate.
+///
+/// @param {String} $font - The font-family to resolve.
+/// @param {Number} $line-height - The line-height to resolve.
+/// @param {String} $size - The font-size to resolve.
+/// @param {String} $tracking - The letter-spacing to resolve.
+/// @param {String} $weight - The font-weight to resolve.
+/// @return {Map} The resolved typography theme with `font`, `line-height`,
+///     `size`, `tracking`, and `weight` tokens.
+@function resolver($args...) {
+  $args: meta.keywords($args);
+  @return (
+    font: map.get($args, font),
+    line-height: _px-to-rem(map.get($args, line-height)),
+    size: _px-to-rem(map.get($args, size)),
+    tracking: _px-to-rem(map.get($args, tracking)),
+    weight: map.get($args, weight)
+  );
+}
+
+@function _px-to-rem($px) {
+  @if $px == null {
+    @return null;
+  }
+
+  @if meta.type-of($px) != 'number' or $px == 0 or not math.compatible($px, 1px)
+  {
+    // Value is something other than px, use as-is.
+    @return $px;
+  }
+
+  @return math.div($px, 16px) * 1rem;
+}
+
+$_reference-theme: (
+  font: null,
+  line-height: null,
+  size: null,
+  tracking: null,
+  weight: null,
+);
+
+@mixin theme-styles($theme) {
+  $theme: theme.validate-theme-styles(
+    $_reference-theme,
+    $theme,
+    $require-all: false
+  );
+  @include _font($theme);
+}
+
+@mixin _font($font) {
+  font-family: map.get($font, font);
+  font-size: map.get($font, size);
+  font-weight: map.get($font, weight);
+  letter-spacing: map.get($font, tracking);
+  line-height: map.get($font, line-height);
+}

package/sass/_var.scss

@@ -0,0 +1,241 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:map';
+@use 'sass:meta';
+@use 'sass:string';
+@use './feature-flags';
+@use './string-ext';
+
+/// Creates a custom property `var()` string according to the configured
+/// `var-fallbacks` feature flag.
+///
+/// @param {String} $name - The name of the custom property.
+/// @param {*} $fallback [null] - Optional `var()` fallback value.
+/// @return {String} A custom property `var()` string.
+@function create($name, $fallback: null) {
+  $name: create-name($name);
+  $fallback-config: feature-flags.get(var-fallbacks);
+  @if $fallback-config == none or $fallback == null {
+    @return var(#{$name});
+  }
+
+  @if is-var($fallback) {
+    $fallback-name: name($fallback);
+    $fallback-fallback: null;
+    @if $fallback-config == all {
+      $fallback-fallback: fallback($fallback);
+    }
+
+    @return var(#{$name}, create($fallback-name, $fallback-fallback));
+  }
+
+  @return var(#{$name}, $fallback);
+}
+
+/// Create a custom property variable name using the configured
+/// `var-name-prefix` feature flag.
+///
+/// Providing a custom property name with `--*` will ignore the global prefix.
+///
+/// @example - scss
+///   .foo {
+///     color: var(#{var.create-name(foo)});
+///     background: var(#{var.create-name(--bar)});
+///   }
+///
+/// @example - css
+///   .foo {
+///     color: var(--md-foo);
+///     background: var(--bar);
+///   }
+///
+/// @param {String} $name - The name of the custom property.
+/// @return {String} The full valid CSS custom property variable name.
+@function create-name($name) {
+  @if string-ext.has-prefix($name, '--') {
+    @return $name;
+  }
+
+  @return string.unquote('--#{feature-flags.get(var-name-prefix)}-#{$name}');
+}
+
+/// Returns the custom property variable name of `var()` string.
+///
+/// @throw If the value is not a custom property.
+/// @param {String} $var - A custom property `var()` string.
+/// @return {String} The custom property variable name.
+@function name($var) {
+  $var: _parse-and-validate($var);
+  @return map.get($var, name);
+}
+
+/// Returns the fallback value of a custom property `var()` string. The value
+/// may be null if the `var()` does not have a fallback value.
+///
+/// @example - scss
+///   $fallback: var.fallback(var(--foo, var(--bar, 8px));
+///   // "var(--bar, 8px)"
+///
+/// @throw If the value is not a custom property.
+/// @param {String} $var - A custom property `var()` string.
+/// @return {String} The fallback value of the `var()` string. May be null if
+///     the `var()` does not have a fallback value.
+@function fallback($var) {
+  $var: _parse-and-validate($var);
+  $fallback: map.get($var, fallback);
+  @if is-var($fallback) {
+    @return create(name($fallback), fallback($fallback));
+  }
+
+  @return $fallback;
+}
+
+/// Returns the deep fallback value of a custom property `var()` string. The
+/// value may be null if the `var()` does not have a fallback value.
+///
+/// If a fallback value is another `var()`, this function will return the final
+/// concrete value in the chain.
+///
+/// @example - scss
+///   $fallback: var.deep-fallback(var(--foo, var(--bar, 8px));
+///   // "8px"
+///
+/// @throw If the value is not a custom property.
+/// @param {String} $var - A custom property `var()` string.
+/// @return {String} The deep fallback value of the `var()` string. May be null
+///     if the `var()` does not have a fallback value.
+@function deep-fallback($var) {
+  $fallback: fallback($var);
+  @if is-var($fallback) {
+    @return deep-fallback($fallback);
+  }
+
+  @return $fallback;
+}
+
+/// Creates a new custom property `var()` string and returns it with the
+/// specified new fallback value.
+///
+/// @example - scss
+///   $new-var: set-fallback(var(--foo, var(--bar, 8px)), 16px);
+///   // "var(--foo, 16px)"
+///
+/// @throw If the value is not a custom property.
+/// @param {String} $var - A custom property `var()` string.
+/// @param {*} $new-fallback - The new fallback value. May be null to remove a
+///     value.
+/// @return {String} A custom property `var()` string with the new fallback
+///     value.
+@function set-fallback($var, $new-fallback) {
+  $name: name($var);
+  @return create($name, $new-fallback);
+}
+
+/// Creates a new custom property `var()` string and returns it with the
+/// specified new deep fallback value.
+///
+/// If the provided `var()` string's fallback value is another `var()`, this
+/// function will set the final fallback value in the chain.
+///
+/// @example - scss
+///   $new-var: deep-set-fallback(var(--foo, var(--bar, 8px)), 16px);
+///   // "var(--foo, var(--bar, 16px))"
+///
+/// @throw If the value is not a custom property.
+/// @param {String} $var - A custom property `var()` string.
+/// @param {*} $new-fallback - The new fallback value. May be null to remove a
+///     value.
+/// @return {String} A custom property `var()` string with the new deep
+///     fallback value.
+@function deep-set-fallback($var, $new-fallback) {
+  $old-fallback: fallback($var);
+  @if is-var($old-fallback) {
+    $new-fallback: deep-set-fallback($old-fallback, $new-fallback);
+  }
+
+  @return set-fallback($var, $new-fallback);
+}
+
+/// Indicates whether or not a value is a custom property `var()` string.
+///
+/// @example - scss
+///   $is-var: var.is-var('var(--foo)'); // true
+///
+/// @param {*} $var - The value to test.
+/// @return {Bool} True if the value is a custom property `var()` string, or
+///     false if not.
+@function is-var($var) {
+  @return _parse($var) != null;
+}
+
+/// Indicates whether or not a value is a `var()` string.
+///
+/// @param {*} $var - The value to test.
+/// @return {Bool} True if the value is a custom property `var()` string, or
+///     false if not.
+@function _is-var-string($var) {
+  @return meta.type-of($var) == 'string' and string-ext.has-prefix($var, 'var(');
+}
+
+/// Parses a `var()` string into a Map with `name` and `fallback` keys. This
+/// function returns null if the value is invalid.
+///
+/// @param {*} $var - The value to parse.
+/// @return {Map} A Map containing a string `name` key with the custom property
+///     name and a `fallback` key with the fallback value (which may be null).
+///     The returned Map itself may be null if the provided value is not valid.
+@function _parse($var) {
+  @if meta.type-of($var) ==
+    'map' and
+    map.has-key($var, name) and
+    map.has-key($var, fallback)
+  {
+    @return $var;
+  }
+
+  @if not _is-var-string($var) {
+    @return null;
+  }
+
+  // Remove function name and parens
+  $var: string-ext.trim($var, 'var(', ')');
+
+  $name: string-ext.trim-repeating($var, ' ');
+  $fallback: null;
+  $comma: string.index($var, ',');
+  @if $comma != null {
+    $name: string-ext.trim-repeating(string.slice($var, 1, $comma - 1), ' ');
+    $fallback: string-ext.trim-repeating(string.slice($var, $comma + 1), ' ');
+    @if _is-var-string($fallback) {
+      $fallback: _parse($fallback);
+      @if $fallback == null {
+        // Invalid var() fallback string
+        @return null;
+      }
+    }
+  }
+
+  @if $name == '' or $fallback == '' {
+    @return null;
+  }
+
+  @return (name: $name, fallback: $fallback);
+}
+
+/// Parses a `var()` string into a Map with `name` and `fallback` keys.
+///
+/// @throw If the value is not a custom property.
+/// @param {*} $var - The value to parse.
+/// @return {Map} A Map containing a string `name` key with the custom property
+///     name and a `fallback` key with the fallback value (which may be null).
+@function _parse-and-validate($var) {
+  $var-map: _parse($var);
+  @if $var-map == null {
+    @error '"#{$var}" is not a valid var() string';
+  }
+
+  @return $var-map;
+}