@material/web 0.1.0-alpha.0

package/sass/_elevation.scss

@@ -0,0 +1,155 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:map';
+@use 'sass:meta';
+@use './color';
+@use './var';
+
+/// Returns the appropriate elevation theme for the given args.
+///
+/// @throw If elevation or shadow color is provided and the other is null.
+/// @throw If a required resolver is missing.
+/// @param {Number} $elevation - The elevation in dp.
+/// @param {Color} $shadow-color - The elevation's shadow color.
+/// @param {Map} $resolvers - Sass resolvers map. Requires `elevation-dp`,
+///     `elevation-shadow`, and `elevation-overlay-opacity` resolvers.
+/// @return {Map} The resolved elevation theme with a `shadow` box-shadow and
+///     `overlay-opacity` for the given elevation and shadow color.
+@function resolver($args...) {
+  $args: meta.keywords($args);
+
+  $dp: map.get($args, elevation);
+  $level: _resolve-dp($dp);
+  $shadow-color: map.get($args, shadow-color);
+
+  @return (
+    shadow: _resolve-box-shadow($level, $shadow-color),
+    overlay-opacity: _resolve-overlay-opacity($level)
+  );
+}
+
+/// Maps elevation dps to elevation levels.
+$_dp-to-level-map: (
+  // TODO: pull the keys from tokens
+  0: 0,
+  1: 1,
+  3: 2,
+  6: 3,
+  8: 4,
+  12: 5
+);
+
+/// Returns the appropriate elevation level for a given dp.
+///
+/// @throw If the provided dp does not map to an elevation level.
+/// @param {Number} $dp - The dp to convert to an elevation level.
+/// @return {Number} The level of the elevation system, or null if the dp is
+///     null.
+@function _resolve-dp($dp) {
+  @if $dp == null {
+    @return null;
+  }
+
+  $level: map.get($_dp-to-level-map, $dp);
+  @if $level == null {
+    @error '#{$dp} is not a valid elevation dp level. Must be one of #{map.keys($_dp-to-level-map)}.';
+  }
+
+  @return $level;
+}
+
+// TODO: pull these values from tokens
+$_key-opacity: 0.3;
+$_ambient-opacity: 0.15;
+$_shadow-map: (
+  0: (
+    key: '0px 0px 0px 0px',
+    ambient: '0px 0px 0px 0px',
+  ),
+  1: (
+    key: '0px 1px 2px 0px',
+    ambient: '0px 1px 3px 1px',
+  ),
+  2: (
+    key: '0px 1px 2px 0px',
+    ambient: '0px 2px 6px 2px',
+  ),
+  3: (
+    key: '0px 1px 3px 0px',
+    ambient: '0px 4px 8px 3px',
+  ),
+  4: (
+    key: '0px 2px 3px 0px',
+    ambient: '0px 6px 10px 4px',
+  ),
+  5: (
+    key: '0px 4px 4px 0px',
+    ambient: '0px 8px 12px 6px',
+  ),
+);
+
+/// Returns the appropriate box-shadow for the given level and shadow color.
+///
+/// @throw If level or shadow-color are provided and one is null.
+/// @param {Number} $level - The level of the elevation system.
+/// @param {Color} $shadow-color - The color of the shadow.
+/// @return {List|String} - The constructed box-shadow, none (for elevation 0),
+///     or null
+@function _resolve-box-shadow($level, $shadow-color) {
+  @if $level == null and $shadow-color == null {
+    @return null;
+  }
+
+  @if $level == 0 {
+    @return none;
+  }
+
+  @if $level == null {
+    @error '$elevation is required when $shadow-color is provided';
+  }
+
+  @if $shadow-color == null {
+    @error '$shadow-color is required when $elevation is provided';
+  }
+
+  $key-spread: map.get($_shadow-map, $level, key);
+  $ambient-spread: map.get($_shadow-map, $level, ambient);
+
+  $key-color: rgba($shadow-color, $_key-opacity);
+  $ambient-color: rgba($shadow-color, $_ambient-opacity);
+
+  @if var.is-var($shadow-color) {
+    // TODO(b/213331407): Convert color from hex to rgba CSS color format to
+    // enable mixing rgb value with alpha using custom properties.
+    // (e.g., rgb(var(--foo-sys-color-on-surface-rgb, 31,31,31), 0.38))
+    // Remove once the attached bug is resolved.
+    $key-color: color.color-var-hex-to-rgba($shadow-color, $_key-opacity);
+    $ambient-color: color.color-var-hex-to-rgba(
+      $shadow-color,
+      $_ambient-opacity
+    );
+  }
+
+  @return (#{$key-spread} #{$key-color}, #{$ambient-spread} #{$ambient-color});
+}
+
+// TODO: pull these values from tokens
+$_overlay-opacity: (
+  0: 0,
+  1: 0.05,
+  2: 0.08,
+  3: 0.11,
+  4: 0.12,
+  5: 0.14,
+);
+
+/// Returns the appropriate overlay opacity for the given level.
+///
+/// @param {Number} $level - The level of the elevation system.
+/// @return {Number} The opacity or null.
+@function _resolve-overlay-opacity($level) {
+  @return map.get($_overlay-opacity, $level);
+}

package/sass/_feature-flags.scss

@@ -0,0 +1,117 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+
+/// Valid configuration values for each config option.
+$_valid-values: (
+  // - all: var(--foo, var(--bar, 8px))
+  // - none: var(--foo)
+  // - vars: var(--foo, var(--bar))
+  var-fallbacks: (all, none, vars)
+);
+
+/// Initial configuration for Sass options.
+$_initial-config: (
+  var-name-prefix: 'md',
+  var-fallbacks: all,
+);
+
+/// The current configuration.
+$_current-config: $_initial-config;
+
+/// Set configuration options for Sass. Setting an option to `null` will reset
+/// the option to its initial value.
+///
+/// The options will only be set within the scope of the content provided to the
+/// mixin.
+///
+/// @example - scss
+///   @include config.set($var-fallbacks: none) {
+///     // 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
+///
+/// @throw If any option is not a valid configuration option.
+/// @throw If any value is not a valid configuration option value.
+/// @content The scope of the configuration.
+/// @param {String} $var-name-prefix [md] - The prefix to use for custom
+///     properties.
+/// @param {String} $var-fallbacks [all] - What to emit for custom property
+///     fallback values. (`all`, `none`, `vars`)
+@mixin set($config...) {
+  @if not meta.content-exists() {
+    @error 'Content scope is required: config.set($options...) { /* scope */ }';
+  }
+
+  $config: meta.keywords($config);
+  @each $option, $value in $config {
+    @if $value == null {
+      $value: map.get($_initial-config, $option);
+    }
+
+    $value: _validate-value($option, $value);
+  }
+
+  $previous-config: $_current-config;
+  // Use !global to avoid shadowing
+  // https://sass-lang.com/documentation/variables#shadowing
+  $_current-config: map.merge($_current-config, $config) !global;
+  // Restore previous config after content scope ends
+  @content;
+  $_current-config: $previous-config !global;
+}
+
+/// Retrieves the current configuration value for the given option.
+///
+/// @throw If the option is not a valid configuration option.
+/// @param {String} option - The config option to get a value for.
+/// @return {*} - The current value for the config option.
+@function get($option) {
+  $option: _validate-option($option);
+  @return map.get($_current-config, $option);
+}
+
+/// Checks that an option is valid and returns it.
+///
+/// @throw If the option is not a valid configuration option.
+/// @param {String} option - The option to check.
+/// @return {String} The provided option.
+@function _validate-option($option) {
+  $valid-options: map.keys($_initial-config);
+  @if list.index($valid-options, $option) == null {
+    @error '"#{$option}" is not a valid configuration option';
+  }
+
+  @return $option;
+}
+
+/// Checks that an option and value are valid and returns the value.
+///
+/// @throw If any option is not a valid configuration option.
+/// @throw If any value is not a valid configuration option value.
+/// @param {String} option - The option to check.
+/// @param {*} option - The value to check.
+/// @return {*} - The provided value option.
+@function _validate-value($option, $value) {
+  $option: _validate-option($option);
+  $valid-values: map.get($_valid-values, $option);
+  @if $valid-values == null {
+    // Any value is acceptable
+    @return $value;
+  }
+
+  @if list.index($valid-values, $value) == null {
+    @error '"#{$option}": "#{$value}" is not a valid configuration value (must be one of #{$valid-values})';
+  }
+
+  @return $value;
+}

package/sass/_map-ext.scss

@@ -0,0 +1,25 @@
+//
+// Copyright 2022 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:map';
+
+/// Picks only specified items in a map.
+///
+/// @example - scss
+///   @debug pick((one: 1, two: 2, three: 3), (two, three));
+///          // (two: 2, three: 3)
+///
+/// @param {Map} $map - Map input to pick.
+/// @param {List} $list - List containing items to pick.
+/// @return {Map} Returns a map containing items specified in `$list`.
+@function pick($map, $list) {
+  $result: ();
+  @each $key in $list {
+    $value: map.get($map, $key);
+    $result: map.set($result, $key, $value);
+  }
+
+  @return $result;
+}

package/sass/_resolvers.scss

@@ -0,0 +1,16 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:meta';
+@use './elevation';
+@use './shape';
+@use './typography';
+
+/// Material Design resolvers.
+$material: (
+  elevation: meta.get-function('resolver', $module: 'elevation'),
+  shape: meta.get-function('resolver', $module: 'shape'),
+  typography: meta.get-function('resolver', $module: 'typography'),
+);

package/sass/_shape.scss

@@ -0,0 +1,106 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use './var';
+
+/// Resolves one or more shape tokens and expands them into 4 separate logical
+/// tokens for each corner.
+///
+/// @example - scss
+///   $theme: (container-shape: (4px 4px 0 0));
+///   $theme: resolve-theme(
+///     $theme,
+///     map.get($resolvers, shape),
+///     container-shape,
+///   );
+///   // (
+///   //   container-shape-start-start: 4px,
+///   //   container-shape-start-end: 4px,
+///   //   container-shape-end-end: 0,
+///   //   container-shape-end-start: 0,
+///   // )
+///
+/// @param {Map} $theme - The theme to resolve tokens for.
+/// @param {Function} $resolver - The shape resolver to use.
+/// @param {String...} $shape-tokens - The shape tokens to resolve.
+/// @return {Map} The theme with resolved shape tokens.
+@function resolve-theme($theme, $resolver, $shape-tokens...) {
+  @if $resolver == null {
+    @return $theme;
+  }
+
+  @each $token in $shape-tokens {
+    $shape-theme: meta.call($resolver, $shape: map.get($theme, $token));
+
+    // Add resolved values, but allow $theme to override the results if needed.
+    $theme: map.merge(
+      (
+        '#{$token}-start-start': map.get($shape-theme, start-start),
+        '#{$token}-start-end': map.get($shape-theme, start-end),
+        '#{$token}-end-end': map.get($shape-theme, end-end),
+        '#{$token}-end-start': map.get($shape-theme, end-start),
+      ),
+      $theme
+    );
+
+    $theme: map.remove($theme, $token);
+  }
+
+  @return $theme;
+}
+
+/// Resolves a shape value by expanding it into logical values for each corner.
+///
+/// @param {Number|List} $shape - The shape token's value.
+/// @return {Map} A map with logical tokens for each corner's value.
+@function resolver($args...) {
+  $args: meta.keywords($args);
+  $shape: map.get($args, shape);
+  @if meta.type-of($shape) != 'list' {
+    @return (
+      start-start: $shape,
+      start-end: $shape,
+      end-end: $shape,
+      end-start: $shape
+    );
+  }
+
+  @if list.length($shape) == 1 {
+    @return (
+      start-start: list.nth($shape, 1),
+      start-end: list.nth($shape, 1),
+      end-end: list.nth($shape, 1),
+      end-start: list.nth($shape, 1)
+    );
+  }
+
+  @if list.length($shape) == 2 {
+    @return (
+      start-start: list.nth($shape, 1),
+      start-end: list.nth($shape, 2),
+      end-end: list.nth($shape, 1),
+      end-start: list.nth($shape, 2)
+    );
+  }
+
+  @if list.length($shape) == 3 {
+    @return (
+      start-start: list.nth($shape, 1),
+      start-end: list.nth($shape, 2),
+      end-end: list.nth($shape, 3),
+      end-start: list.nth($shape, 2)
+    );
+  }
+
+  @return (
+    start-start: list.nth($shape, 1),
+    start-end: list.nth($shape, 2),
+    end-end: list.nth($shape, 3),
+    end-start: list.nth($shape, 4)
+  );
+}

package/sass/_string-ext.scss

@@ -0,0 +1,128 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'sass:string';
+
+/// Checks if a string starts with a given prefix.
+///
+/// @example - scss
+///   @debug has-prefix('var(--foo)', 'var('); // true
+///
+/// @param {String} $string - The string to test.
+/// @param {String} $prefix - The prefix to check.
+/// @return {Boolean} True if the string starts with the given prefix.
+@function has-prefix($string, $prefix) {
+  @return string.slice($string, 1, string.length($prefix)) == $prefix;
+}
+
+/// Checks if a string ends with a given suffix.
+///
+/// @example - scss
+///   @debug has-suffix('var(--foo)', ')'); // true
+///
+/// @param {String} $string - The string to test.
+/// @param {String} $suffix - The suffix to check.
+/// @return {Boolean} True if the string ends with the given suffix.
+@function has-suffix($string, $suffix) {
+  @return string.slice($string, -1 * string.length($suffix)) == $suffix;
+}
+
+/// Trims a repeating prefix from the start of a string.
+///
+/// @example - scss
+///   @debug trim-repeating-prefix('  foo bar  ', ' '); // "foo bar  "
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $prefix - The repeating prefix string to trim.
+/// @return {String} The string with the prefix trimmed from the start.
+@function trim-repeating-prefix($string, $prefix) {
+  @while has-prefix($string, $prefix) {
+    $string: trim-prefix($string, $prefix);
+  }
+
+  @return $string;
+}
+
+/// Trims a prefix from the start of a string.
+///
+/// @example - scss
+///   @debug trim-prefix('var(--foo)', 'var('); // "--foo)"
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $prefix - The prefix string to trim.
+/// @return {String} The string with the prefix trimmed from the start.
+@function trim-prefix($string, $prefix) {
+  @if has-prefix($string, $prefix) {
+    $string: string.slice($string, string.length($prefix) + 1);
+  }
+
+  @return $string;
+}
+
+/// Trims a repeating suffix from the end of a string.
+///
+/// @example - scss
+///   @debug trim-repeating-suffix('  foo bar  ', ' '); // "  foo bar"
+///   @debug trim-repeating-suffix('var(--foo)', ')'); // "var(--foo"
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $suffix - The repeating suffix string to trim.
+/// @return {String} The string with the suffix trimmed from the end.
+@function trim-repeating-suffix($string, $suffix) {
+  @while has-suffix($string, $suffix) {
+    $string: trim-suffix($string, $suffix);
+  }
+
+  @return $string;
+}
+
+/// Trims a suffix from the end of a string.
+///
+/// @example - scss
+///   @debug trim-suffix('var(--foo)', ')'); // "var(--foo"
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $suffix - The suffix string to trim.
+/// @return {String} The string with the suffix trimmed from the end.
+@function trim-suffix($string, $suffix) {
+  @if has-suffix($string, $suffix) {
+    $string: string.slice($string, 1, -1 * string.length($suffix) - 1);
+  }
+
+  @return $string;
+}
+
+/// Trims a repeating prefix and suffix from the start and end of a string.
+///
+/// If a suffix is not provided, the prefix is used as the suffix to trim.
+///
+/// @example - scss
+///   @debug trim-repeating('  foo bar  ', ' '); // "foo bar"
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $prefix - The repeating prefix string to trim.
+/// @param {String} $suffix [$prefix] - The repeating suffix string to trim.
+/// @return {String} The string with the prefix and suffix trimmed.
+@function trim-repeating($string, $prefix, $suffix: $prefix) {
+  @return trim-repeating-prefix(
+    trim-repeating-suffix($string, $suffix),
+    $prefix
+  );
+}
+
+/// Trims a prefix and suffix from the start and end of a string.
+///
+/// If a suffix is not provided, the prefix is used as the suffix to trim.
+///
+/// @example - scss
+///   @debug trim('var(--foo)', 'var(', ')'); // "--foo"
+///
+/// @param {String} $string - The string to trim.
+/// @param {String} $prefix - The prefix string to trim.
+/// @param {String} $suffix [$prefix] - The suffix string to trim.
+/// @return {String} The string with the prefix and suffix trimmed.
+@function trim($string, $prefix, $suffix: $prefix) {
+  @return trim-prefix(trim-suffix($string, $suffix), $prefix);
+}