@material/web 2.4.1 → 2.4.2-nightly.555b0ad.0

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;
+}

package/{internal/sass → sass/ext}/_var.scss

@@ -3,90 +3,79 @@
 // SPDX-License-Identifier: Apache-2.0
 //
 
-// go/keep-sorted start
+// Utility functions for "var()" custom property string manipulation.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
 @use 'sass:map';
 @use 'sass:meta';
 @use 'sass:string';
-// go/keep-sorted end
-// go/keep-sorted start
-@use './string-ext';
+@use 'assert';
+@use 'string_ext';
+@use 'throw';
 // go/keep-sorted end
 
 /// Creates a custom property `var()` string.
 ///
-/// @param {String} $name - The name of the custom property.
+/// @example scss
+///   @debug var.create(--foo); // "var(--foo)"
+///   @debug var.create(--foo, 8px); // "var(--foo, 8px)"
+///
+/// @param {string} $name - The name of the custom property.
 /// @param {*} $fallback [null] - Optional `var()` fallback value.
-/// @return {String} A custom property `var()` string.
+/// @return {string} A custom property `var()` string.
 @function create($name, $fallback: null) {
-  $name: create-name($name);
-  @if $fallback == null {
-    @return var(#{$name});
+  $name: assert.is-type($name, 'string');
+  @if throw.get-error($name) {
+    @return $name;
   }
-
-  @if is-var($fallback) {
-    $fallback-name: name($fallback);
-    $fallback-fallback: fallback($fallback);
-    @return var(#{$name}, create($fallback-name, $fallback-fallback));
+  @if not string_ext.starts-with($name, '--') {
+    @return throw.error(
+      'Custom property names must start with "--". $name: #{meta.inspect($name)}',
+      $source: 'var.create'
+    );
   }
 
-  @return var(#{$name}, $fallback);
-}
-
-/// Create a custom property variable name.
-///
-/// 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;
+  @if $fallback == null {
+    @return var(#{$name});
   }
 
-  @return string.unquote('--md-#{$name}');
+  @return var(#{$name}, #{$fallback});
 }
 
 /// Returns the custom property variable name of `var()` string.
 ///
+/// @example scss
+///   $var: var(--foo);
+///   @debug var.name($var); // "--foo"
+///
+/// @param {string} $var - A custom property `var()` string.
+/// @return {string} The custom property variable name.
 /// @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);
+  @if throw.get-error($var) {
+    @return $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)"
+/// @example scss
+///   $var: var(--foo, var(--bar, 8px));
+///   @debug var.fallback($var); // "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
+/// @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.
+/// @throw If the value is not a custom property.
 @function fallback($var) {
   $var: _parse-and-validate($var);
-  $fallback: map.get($var, fallback);
-  @if is-var($fallback) {
-    @return create(name($fallback), fallback($fallback));
+  @if throw.get-error($var) {
+    @return $var;
   }
-
-  @return $fallback;
+  @return map.get($var, 'fallback');
 }
 
 /// Returns the deep fallback value of a custom property `var()` string. The
@@ -95,18 +84,18 @@
 /// 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"
+/// @example scss
+///   $var: var(--foo, var(--bar, 8px));
+///   @debug var.deep-fallback($var); // "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
+/// @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.
+/// @throw If the value is not a custom property.
 @function deep-fallback($var) {
   $fallback: fallback($var);
-  @if is-var($fallback) {
-    @return deep-fallback($fallback);
+  @while is-var($fallback) {
+    $fallback: fallback($fallback);
   }
 
   @return $fallback;
@@ -115,16 +104,17 @@
 /// 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)"
+/// @example scss
+///   $var: var(--foo, var(--bar, 8px));
+///   $new-var: set-fallback($var, 16px);
+///   @debug $new-var; // "var(--foo, 16px)"
 ///
-/// @throw If the value is not a custom property.
-/// @param {String} $var - A custom property `var()` string.
+/// @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
+/// @return {string} A custom property `var()` string with the new fallback
 ///     value.
+/// @throw If the value is not a custom property.
 @function set-fallback($var, $new-fallback) {
   $name: name($var);
   @return create($name, $new-fallback);
@@ -136,16 +126,17 @@
 /// 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))"
+/// @example scss
+///   $var: var(--foo, var(--bar, 8px));
+///   $new-var: var.deep-set-fallback($var, 16px);
+///   @debug $new-var; // "var(--foo, var(--bar, 16px))"
 ///
-/// @throw If the value is not a custom property.
-/// @param {String} $var - A custom property `var()` string.
+/// @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
+/// @return {string} A custom property `var()` string with the new deep
 ///     fallback value.
+/// @throw If the value is not a custom property.
 @function deep-set-fallback($var, $new-fallback) {
   $old-fallback: fallback($var);
   @if is-var($old-fallback) {
@@ -157,11 +148,12 @@
 
 /// Indicates whether or not a value is a custom property `var()` string.
 ///
-/// @example - scss
-///   $is-var: var.is-var('var(--foo)'); // true
+/// @example scss
+///   $var: var(--foo);
+///   @debug var.is-var($var); // true
 ///
 /// @param {*} $var - The value to test.
-/// @return {Bool} True if the value is a custom property `var()` string, or
+/// @return {boolean} True if the value is a custom property `var()` string, or
 ///     false if not.
 @function is-var($var) {
   @return _parse($var) != null;
@@ -170,24 +162,25 @@
 /// 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
+/// @return {boolean} 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(');
+  @return meta.type-of($var) == 'string' and
+    string_ext.starts-with($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
+/// @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)
+    map.has-key($var, 'name') and
+    map.has-key($var, 'fallback')
   {
     @return $var;
   }
@@ -197,40 +190,37 @@
   }
 
   // Remove function name and parens
-  $var: string-ext.trim($var, 'var(', ')');
+  $var: string_ext.replace-start($var, 'var(', '');
+  $var: string_ext.replace-end($var, ')', '');
 
-  $name: string-ext.trim-repeating($var, ' ');
+  $name: string_ext.trim($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;
-      }
-    }
+    $name: string_ext.trim(string.slice($var, 1, $comma - 1));
+    $fallback: string_ext.trim(string.slice($var, $comma + 1));
   }
 
   @if $name == '' or $fallback == '' {
     @return null;
   }
 
-  @return (name: $name, fallback: $fallback);
+  @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
+/// @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).
+/// @throw If the value is not a custom property.
 @function _parse-and-validate($var) {
   $var-map: _parse($var);
   @if $var-map == null {
-    @error '"#{$var}" is not a valid var() string';
+    @return throw.error(
+      '#{meta.inspect($var)} is not a valid var() string',
+      $source: 'var._parse-and-validate'
+    );
   }
 
   @return $var-map;

package/sass/ext/tests.css

@@ -0,0 +1 @@
+/*# sourceMappingURL=tests.css.map */

package/sass/ext/tests.css.map

@@ -0,0 +1 @@
+{"version":3,"sourceRoot":"","sources":[],"names":[],"mappings":"","file":"tests.css"}

package/sass/ext/tests.scss

@@ -0,0 +1,18 @@
+//
+// Copyright 2021 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+@use 'true' as test with (
+  $catch-errors: true
+);
+
+// go/keep-sorted start
+@use 'assert_test';
+@use 'list_ext_test';
+@use 'map_ext_test';
+@use 'string_ext_test';
+@use 'throw_test';
+@use 'type_test';
+@use 'var_test';
+// go/keep-sorted end

package/slider/internal/_slider.scss

@@ -121,6 +121,7 @@ $_md-sys-shape: tokens.md-sys-shape-values();
     pointer-events: none;
     // ensure scrolling is prevented on mobile.
     touch-action: none;
+    user-select: none;
   }
 
   .track,