@material/web 2.4.1 → 2.4.2-nightly.082faad.0

package/sass/ext/_map_ext.scss

@@ -0,0 +1,222 @@
+//
+// Copyright 2025 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Extensions to the go/sass:map built-in module.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use 'assert';
+@use 'throw';
+@use 'type';
+// go/keep-sorted end
+
+/// The same as `map.get()` but throws an error if the key is not found.
+///
+/// This is useful over `map.get()` when using Sass maps like records, where
+/// the key is expected to exist.
+///
+/// @example scss
+///   $map: (
+///     'name': 'foo',
+///     'value': blue,
+///   );
+///
+///   @debug map_ext.get-strict($map, 'name'); // 'foo'
+///   @debug map_ext.get-strict($map, 'bar'); // ERROR: Key "bar" expected but not found in $map: ('name': 'foo', 'value': blue)
+///
+/// @param {map} $map - The map to retrieve the value from.
+/// @param {string} $key - The key of the value to retrieve.
+/// @param {list} $keys - Additional keys to retrieve deeply nested values.
+/// @return {*} The value at the given key.
+/// @throw Error if the key does not exist in the map.
+@function get-strict($map, $key, $keys...) {
+  $map: assert.is-type($map, 'map', $source: 'map_ext.get-strict');
+  @if throw.get-error($map) {
+    @return $map;
+  }
+  @if not map.has-key($map, $key, $keys...) {
+    @return throw.error(
+      'Key #{$key} expected but not found in $map: #{meta.inspect($map)}',
+      $source: 'map.get-strict'
+    );
+  }
+
+  @return map.get($map, $key, $keys...);
+}
+
+/// Splits a Map and returns a List pair with two new Maps: the first with the
+/// provided keys and the second without.
+///
+/// @example scss
+///   $map: (
+///     'focus': blue,
+///     'focus-within': blue,
+///     'hover': teal,
+///     'active': green,
+///   );
+///
+///   $pair: map_ext.split($map, ('focus', 'focus-within'));
+///
+///   $map-with-focus-keys: list.nth($pair, 1);
+///   @debug $map-with-focus-keys; // ('focus': blue, 'focus-within': blue)
+///
+///   $map-with-remaining-keys: list.nth($pair, 2);
+///   @debug $map-with-remaining-keys; // ('hover': teal, 'active': green)
+///
+/// @param {map} $map - The Map to split.
+/// @param {list} $keys - List of keys to split the Map by.
+/// @return {list} A List pair with two new Maps: the first with the keys
+///     provided, and the second with the remaining keys.
+@function split($map, $keys) {
+  @if type.matches($keys, 'string') {
+    // A list with a single string `('key')` collapses to a single string type
+    // at build time. We can force it to be a list using a list API method.
+    // Ex:
+    // map_ext.split($map, ('key')) is the same as
+    // map_ext.split($map, 'key')
+    $keys: list.append((), $keys);
+  }
+
+  // In Sass, `()` counts as both a map and a list, and always reports its type
+  // as a list. If we're given an empty map-list, we don't need to throw a type
+  // error.
+  $map: assert.is-type($map, 'map|list', $source: 'map_ext.split');
+  $keys: assert.is-type($keys, 'list', $source: 'map_ext.split');
+  $error: throw.get-error($map, $keys);
+  @if not $error and list.length($keys) == 0 {
+    $error: throw.error(
+      'List of keys to split by are empty',
+      $source: 'map_ext.split'
+    );
+  }
+  @if $error {
+    @return $error;
+  }
+
+  // In Sass, `()` is an empty list. We can force Sass to use map types by
+  // creating the map with map APIs. This ensures that even if a map is empty,
+  // `meta.type-of()` will report it as a map.
+  $map-with-keys: map.merge((), ());
+  $map-without-keys: map.merge((), ());
+  @each $key, $value in $map {
+    $has-key: list.index($keys, $key) != null;
+    @if $has-key {
+      $map-with-keys: map.set($map-with-keys, $key, $value);
+    } @else {
+      $map-without-keys: map.set($map-without-keys, $key, $value);
+    }
+  }
+
+  @return ($map-with-keys, $map-without-keys);
+}
+
+/// Splits a Map and returns a new Map that only includes the provided keys.
+///
+/// @example scss
+///   $map: (
+///     'focus': blue,
+///     'focus-within': blue,
+///     'hover': teal,
+///     'active': green,
+///   );
+///
+///   $map-with-focus-keys: map_ext.pick($map, ('focus', 'focus-within'));
+///   @debug $map-with-focus-keys; // ('focus': blue, 'focus-within': blue)
+///
+/// @param {map} $map - The Map to split.
+/// @param {list} $keys - List of keys to include in the new Map.
+/// @return {map} Map with only the keys provided.
+@function pick($map, $keys) {
+  $result: split($map, $keys);
+  @if throw.get-error($result) {
+    @return $result;
+  }
+  @return list.nth($result, 1);
+}
+
+/// Splits a Map and returns a new Map that excludes the provided keys.
+///
+/// @example scss
+///   $map: (
+///     'focus': blue,
+///     'focus-within': blue,
+///     'hover': teal,
+///     'active': green,
+///   );
+///
+///   $map-without-focus-keys: map_ext.omit($map, ('focus', 'focus-within'));
+///   @debug $map-without-focus-keys; // ('hover': teal, 'active': green)
+///
+/// @param {map} $map - The Map to split.
+/// @param {list} $keys - List of keys to exclude from the new Map.
+/// @return {map} Map without the keys provided.
+@function omit($map, $keys) {
+  $result: split($map, $keys);
+  @if throw.get-error($result) {
+    @return $result;
+  }
+  @return list.nth($result, 2);
+}
+
+/// Returns the given map with any matching keys renamed according to the
+/// provided Map of keys to rename.
+///
+/// @example scss
+///   $map: ('foo': red);
+///
+///   $new-map: map_ext.rename-keys($map, ('foo': 'bar'));
+///   @debug $new-map; // ('bar': red)
+///
+/// @param {map} $map - The map to rename keys within.
+/// @param {map} $keys-to-rename - A map of keys and their new names.
+/// @return {map} The map with any matching keys renamed.
+@function rename-keys($map, $keys-to-rename) {
+  $new-map: omit($map, map.keys($keys-to-rename));
+  @if throw.get-error($new-map) {
+    @return $new-map;
+  }
+
+  @each $old-key-name, $new-key-name in $keys-to-rename {
+    @if map.has-key($map, $old-key-name) {
+      $new-map: map.set($new-map, $new-key-name, map.get($map, $old-key-name));
+    }
+  }
+
+  @return $new-map;
+}
+
+/// Returns a list of keys where $mapB diverges from $mapA.
+/// Divergence occurs when:
+///   1. A key exists in $mapB but not in $mapA.
+///   2. A key exists in both maps but with different values.
+///
+/// @example scss
+///   $mapA: ('foo': red, 'bar': yellow, 'baz': 10);
+///   $mapB: ('foo': red, 'bar': green,  'baz': 10, 'fooBar': blue);
+///
+///   $differences: map_ext.difference($mapA, $mapB);
+///   @debug $differences; // ('bar', 'fooBar')
+///
+/// @param {map} $mapA - The reference map.
+/// @param {map} $mapB - The map to compare against the reference.
+/// @return {list} A list of keys where $mapB diverges from $mapA.
+@function difference($mapA, $mapB) {
+  $mapA: assert.is-type($mapA, 'map', $source: 'map_ext.difference');
+  $mapB: assert.is-type($mapB, 'map', $source: 'map_ext.difference');
+  $error: throw.get-error($mapA, $mapB);
+  @if $error {
+    @return $error;
+  }
+  $differences: ();
+  @each $key, $value in $mapB {
+    @if not map.has-key($mapA, $key) or map.get($mapA, $key) != $value {
+      $differences: list.append($differences, $key);
+    }
+  }
+
+  @return $differences;
+}

package/sass/ext/_string_ext.scss

@@ -0,0 +1,153 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Extensions to the go/sass:string built-in module.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
+@use 'sass:list';
+@use 'sass:string';
+// go/keep-sorted end
+
+/// Checks if a string starts with a given prefix.
+///
+/// @example scss
+///   @debug string_ext.starts-with('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 starts-with($string, $prefix) {
+  @return string.slice($string, 1, string.length($prefix)) == $prefix;
+}
+
+/// Checks if a string ends with a given suffix.
+///
+/// @example scss
+///   @debug string_ext.ends-with('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 ends-with($string, $suffix) {
+  @return string.slice($string, -1 * string.length($suffix)) == $suffix;
+}
+
+/// Trims leading whitespace from the start of a string.
+///
+/// @example scss
+///   @debug string_ext.trim-start('  foo bar  '); // "foo bar  "
+///
+/// @param {string} $string - The string to trim.
+/// @return {string} The string with whitespace trimmed from the start.
+@function trim-start($string) {
+  @while starts-with($string, ' ') {
+    $string: replace-start($string, ' ', '');
+  }
+
+  @return $string;
+}
+
+/// Trims trailing whitespace from the end of a string.
+///
+/// @example scss
+///   @debug string_ext.trim-end('  foo bar  '); // "  foo bar"
+///
+/// @param {string} $string - The string to trim.
+/// @return {string} The string with trailing whitespace trimmed from the end.
+@function trim-end($string) {
+  @while ends-with($string, ' ') {
+    $string: replace-end($string, ' ', '');
+  }
+
+  @return $string;
+}
+
+/// Trims leading and trailing whitespace from a string.
+///
+/// @example scss
+///   @debug string_ext.trim('  foo bar  '); // "foo bar"
+///
+/// @param {string} $string - The string to trim.
+/// @return {string} The string with leading and trailing whitespace trimmed.
+@function trim($string) {
+  @return trim-start(trim-end($string));
+}
+
+/// Returns a new string with the first match of a pattern replaced by a given
+/// string.
+///
+/// @example scss
+///   @debug string_ext.replace('foo bar baz', 'bar', 'quux'); // "foo quux baz"
+///
+/// @param {string} $string - The string to be searched.
+/// @param {string} $pattern - The pattern to search for.
+/// @param {string} $replacement - The value to replace the pattern.
+/// @return {string} The string with the first match of pattern replaced by the
+///     replacement or the initial string itself.
+@function replace($string, $pattern, $replacement) {
+  $pattern-index: string.index($string, $pattern);
+  @if not $pattern-index {
+    @return $string;
+  }
+
+  $before: string.slice($string, 1, $pattern-index - 1);
+  $after: string.slice($string, string.length($pattern) + $pattern-index);
+
+  @return $before + $replacement + $after;
+}
+
+/// Returns a new string with all matches of a pattern replaced by a given
+/// string.
+///
+/// @example scss
+///   @debug string_ext.replace-all('foo bar baz', 'ba', 'qua'); // "foo quar quaz"
+///
+/// @param {string} $string - The string to be searched.
+/// @param {string} $pattern - The pattern to search for.
+/// @param {string} $replacement - The value to replace the pattern.
+/// @return {string} The string with all matches of pattern replaced by the
+///     replacement or the initial string itself.
+@function replace-all($string, $pattern, $replacement) {
+  @while string.index($string, $pattern) {
+    $string: replace($string, $pattern, $replacement);
+  }
+
+  @return $string;
+}
+
+/// Returns a new string that replaces a prefix at the start of the string.
+///
+/// @example scss
+///   @debug string_ext.replace-start('var(--foo)', 'var(', ''); // "--foo)"
+///
+/// @param {string} $string - The string to be searched.
+/// @param {string} $prefix - The prefix string to replace.
+/// @param {string} $replacement - The value to replace the prefix.
+/// @return {string} The string with the prefix replaced.
+@function replace-start($string, $prefix, $replacement) {
+  @if starts-with($string, $prefix) {
+    $string: $replacement + string.slice($string, string.length($prefix) + 1);
+  }
+
+  @return $string;
+}
+
+/// Returns a new string that replaces a suffix at the end of the string.
+///
+/// @example scss
+///   @debug string_ext.replace-end('var(--foo)', ')', ''); // "var(--foo"
+///
+/// @param {string} $string - The string to be searched.
+/// @param {string} $suffix - The suffix string to replace.
+/// @param {string} $replacement - The value to replace the suffix.
+/// @return {string} The string with the suffix trimmed from the end.
+@function replace-end($string, $suffix, $replacement) {
+  @if ends-with($string, $suffix) {
+    $string: string.slice($string, 1, -1 * string.length($suffix) - 1) +
+      $replacement;
+  }
+
+  @return $string;
+}

package/sass/ext/_throw.scss

@@ -0,0 +1,83 @@
+//
+// Copyright 2025 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Utilities for `sass-true` errors, to support testing error behavior.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
+@use 'sass:meta';
+@use 'sass:string';
+// go/keep-sorted end
+
+@forward 'true' show error;
+
+/// Returns false if none of the given values are error strings, or returns an
+/// error string if any value has an error.
+///
+/// This is used to support testing error behavior with `sass-true`, since
+/// `@error` messages cannot be caught at build time.
+///
+/// @example scss
+///   // A function that may return an "ERROR:" string in a test.
+///   @function get-value($map, $key) {
+///     @if meta.type-of($map) != 'map' {
+///       // Identical to `@error 'ERROR: Arg is not a map'` outside of tests.
+///       @return throw.error('Arg is not a map');
+///     }
+///     @return map.get($map, $key);
+///   }
+///
+///   // A function that needs to handle potential errors from other functions.
+///   @function mix-primary-on-surface($values) {
+///     $primary: get-value($values, 'primary');
+///     $surface: get-value($values, 'surface');
+///     $error: throw.get-error($primary, $surface);
+///     @if $error {
+///       // Return early to guard logic against additional errors since
+///       // $primary or $surface may be a string instead of a color.
+///       @return $error;
+///     }
+///
+///     @return color.mix($primary, $surface, 10%);
+///   }
+///
+/// Note: `throw.error()` and `throw.get-error()` are only useful when testing
+/// error behavior using `sass-true`. If you are not testing a function, use
+/// `@error` instead.
+///
+/// @example scss
+///   // In a `sass-true` test, `throw.get-error()` can be used to assert that
+///   // an error is thrown.
+///   @use 'true' as test with ($catch-errors: true);
+///
+///   @include test.describe('module.get-value()') {
+///     @include test.it('throws an error if the value is not a map') {
+///       $result: module.get-value('not a map', 'primary');
+///       @include test.assert-truthy(throw.get-error($result), '$result is an error');
+///     }
+///   }
+///
+/// @param {*} $error - The value to check.
+/// @param {list} $errors - Additional values to check. Useful for checking
+///     multiple errors at the same time.
+/// @return {string|boolean} The error string if any value is an error, or false
+///     otherwise.
+@function get-error($error, $errors...) {
+  @if _is-error($error) {
+    @return $error;
+  }
+
+  @each $additional-error in $errors {
+    @if _is-error($additional-error) {
+      @return $additional-error;
+    }
+  }
+
+  @return false;
+}
+
+@function _is-error($error) {
+  @return (meta.type-of($error) == 'string') and
+    (string.index($error, 'ERROR') == 1);
+}

package/sass/ext/_type.scss

@@ -0,0 +1,66 @@
+//
+// Copyright 2025 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Utilities for Sass type checking.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
+@use 'sass:meta';
+@use 'sass:string';
+@use 'throw';
+// go/keep-sorted end
+
+/// Returns true if the given value matches the provided type string.
+///
+/// The type string supports multiple types separated by `|`, such as
+/// `'string|null'`. Type options are any values returned by `meta.type-of()`.
+///
+/// @example scss
+///   @function is-empty($value) {
+///     @if type.matches($value, 'list|map') {
+///       @return list.length($value) == 0;
+///     }
+///     @if type.matches($value, 'string') {
+///       @return $value == '';
+///     }
+///     @return type.matches($value, 'null');
+///   }
+///
+/// @param {*} $value - The value to check the type of.
+/// @param {string} $type-string - The type to check. May be multiple types
+///     separated by `|`.
+/// @return {boolean} True if the value matches the type string.
+@function matches($value, $type-string) {
+  @if meta.type-of($type-string) != 'string' or $type-string == '' {
+    @return throw.error(
+      '$type-string must be a non-empty string',
+      $source: 'type.matches'
+    );
+  }
+  @if string.index($type-string, ' ') {
+    @return throw.error(
+      '$type-string may not contain spaces',
+      $source: 'type.matches'
+    );
+  }
+  @if string.index($type-string, 'boolean') {
+    @return throw.error(
+      'Use "bool" instead of "boolean"',
+      $source: 'type.matches'
+    );
+  }
+
+  $value-type: meta.type-of($value);
+  @if $value-type == $type-string {
+    @return true;
+  }
+
+  @each $type in string.split($type-string, '|') {
+    @if $value-type == $type {
+      @return true;
+    }
+  }
+
+  @return false;
+}