@material/web 2.4.2-nightly.563da62.0 → 2.4.2-nightly.a7ba471.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@material/web",
-  "version": "2.4.2-nightly.563da62.0",
+  "version": "2.4.2-nightly.a7ba471.0",
   "publishConfig": {
     "access": "public"
   },

package/sass/ext/_assert.scss

@@ -54,7 +54,7 @@
 /// returned, otherwise an error is thrown.
 ///
 /// @example scss
-///   @function get-or-throw($map, $key) {
+///   @function get-strict($map, $key) {
 ///     @return assert.not-type(
 ///       map.get($map, $key),
 ///       'null',

package/sass/ext/_list_ext.scss

@@ -0,0 +1,114 @@
+//
+// Copyright 2025 Google LLC
+// SPDX-License-Identifier: Apache-2.0
+//
+
+// Extensions to the go/sass:list built-in module.
+
+// go/keep-sorted start by_regex='(.+) prefix_order=sass:
+@use 'sass:list';
+@use 'assert';
+@use 'throw';
+// go/keep-sorted end
+
+/// Returns the difference between two lists.
+///
+/// @example scss
+///   $listA: ('apple', 'banana', 'cherry', 'date');
+///   $listB: ('banana', 'cherry', 'apple');
+///   $listC: ('apple', 'banana', 'date');
+///
+///   @debug list_ext.difference($listA, $listB); // ('date')
+///   @debug list_ext.difference($listA, $listC); // ('cherry')
+///
+/// @param {list} $listA - The first list to compare.
+/// @param {list} $listB - The second list to compare.
+/// @return {list} All items in $listA that are not in $listB.
+@function difference($listA, $listB) {
+  $listA: assert.is-type($listA, 'list', $source: 'list_ext.difference');
+  $listB: assert.is-type($listB, 'list', $source: 'list_ext.difference');
+  $error: throw.get-error($listA, $listB);
+  @if $error {
+    @return $error;
+  }
+
+  $result: ();
+  @each $item in $listA {
+    @if not list.index($listB, $item) {
+      $result: list.append($result, $item, list.separator($listA));
+    }
+  }
+  @return $result;
+}
+
+/// Checks if two lists contain the same elements, regardless of their order.
+///
+/// The function iterates through each list and verifies that every element in
+/// one list is present in the other. The order of elements does not affect the
+/// result.
+///
+/// @example scss
+///   $listA: ('apple', 'banana', 'cherry');
+///   $listB: ('banana', 'cherry', 'apple');
+///   $listC: ('apple', 'banana', 'date');
+///
+///   @debug list_ext.are-equal($listA, $listB); // true
+///   @debug list_ext.are-equal($listA, $listC); // false
+///
+/// @param {list} $listA - The first list to compare.
+/// @param {list} $listB - The second list to compare.
+/// @return {boolean} `true` if the lists contain the same elements, otherwise
+///     `false`.
+@function are-equal($listA, $listB) {
+  $listA: assert.is-type($listA, 'list', $source: 'list_ext.are-equal');
+  $listB: assert.is-type($listB, 'list', $source: 'list_ext.are-equal');
+  $error: throw.get-error($listA, $listB);
+  @if $error {
+    @return $error;
+  }
+  @if list.length($listA) != list.length($listB) {
+    @return false;
+  }
+  $result: true;
+  @each $key in $listA {
+    @if not list.index($listB, $key) {
+      $result: false;
+    }
+  }
+
+  @each $key in $listB {
+    @if not list.index($listA, $key) {
+      $result: false;
+    }
+  }
+  @return $result;
+}
+
+/// Returns the intersection of two lists.
+///
+/// @example scss
+///   $listA: ('apple', 'banana', 'cherry', 'date');
+///   $listB: ('banana', 'cherry', 'apple');
+///   $listC: ('apple', 'banana', 'date');
+///
+///   @debug list_ext.intersection($listA, $listB); // ('apple', 'banana', 'cherry')
+///   @debug list_ext.intersection($listA, $listC); // ('apple', 'banana')
+///
+/// @param {list} $listA - The first list to compare.
+/// @param {list} $listB - The second list to compare.
+/// @return {list} All items in $listA that are also in $listB.
+@function intersection($listA, $listB) {
+  $listA: assert.is-type($listA, 'list', $source: 'list_ext.intersection');
+  $listB: assert.is-type($listB, 'list', $source: 'list_ext.intersection');
+  $error: throw.get-error($listA, $listB);
+  @if $error {
+    @return $error;
+  }
+  $result: ();
+  @each $item in $listA {
+    @if list.index($listB, $item) {
+      $result: list.append($result, $item, list.separator($listA));
+    }
+  }
+  @return $result;
+}

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/{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 '../../sass/ext/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.starts-with($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,7 +162,7 @@
 /// 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
@@ -181,14 +173,14 @@
 /// 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;
   }
@@ -207,32 +199,28 @@
   @if $comma != null {
     $name: string_ext.trim(string.slice($var, 1, $comma - 1));
     $fallback: string_ext.trim(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);
+  @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.scss

@@ -9,7 +9,10 @@
 
 // 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