CHANGELOG.md

@@ -1,3 +1,71 @@
+## 1.56.0
+
+* **Potentially breaking change:** To match the CSS spec, SassScript expressions
+  beginning with `not` or `(` are no longer supported at the beginning of
+  parenthesized sections of media queries. For example,
+
+  ```scss
+  @media (width >= 500px) and (not (grid))
+  ```
+
+  will now be emitted unchanged, instead of producing
+
+  ```scss
+  @media (width >= 500px) and (false)
+  ```
+
+  See [the Sass website](https://sass-lang.com/d/media-logic) for details.
+
+* **Potentially breaking bug fix:** Angle units like `rad` or `turn` are now
+  properly converted to equivalent `deg` values for `hsl()`, `hsla()`,
+  `adjust-hue()`, `color.adjust()`, and `color.change()`.
+
+  See [the Sass website](https://sass-lang.com/d/function-units#hue) for
+  details.
+
+* Fix indentation for selectors that span multiple lines in a `@media` query.
+
+* Emit a deprecation warning when passing `$alpha` values with units to
+  `color.adjust()` or `color.change()`. This will be an error in Dart Sass
+  2.0.0.
+
+  See [the Sass website](https://sass-lang.com/d/function-units#alpha) for
+  details.
+
+* Emit a deprecation warning when passing a `$weight` value with no units or
+  with units other than `%` to `color.mix()`. This will be an error in Dart Sass
+  2.0.0.
+
+  See [the Sass website](https://sass-lang.com/d/function-units#weight) for
+  details.
+
+* Emit a deprecation warning when passing `$n` values with units to `list.nth()`
+  or `list.set-nth()`. This will be an error in Dart Sass 2.0.0.
+
+  See [the Sass website](https://sass-lang.com/d/function-units#index) for
+  details.
+
+* Improve existing deprecation warnings to wrap `/`-as-division suggestions in
+  `calc()` expressions.
+
+* Properly mark the warning for passing numbers with units to `random()` as a
+  deprecation warning.
+
+* Fix a bug where `@extend` could behave unpredicatably when used along with
+  `meta.load-css()` and shared modules that contained no CSS themselves but
+  loaded CSS from other modules.
+
+### Dart API
+
+* Emit a deprecation warning when passing a `sassIndex` with units to
+  `Value.sassIndexToListIndex()`. This will be an error in Dart Sass 2.0.0.
+
+### JS API
+
+* Importer results now validate whether `contents` is actually a string type.
+
+* Importer result argument errors are now rendered correctly.
+
 ## 1.55.0
 
 * **Potentially breaking bug fix:** Sass numbers are now universally stored as

lib/src/async_environment.dart

@@ -1014,7 +1014,7 @@ class _EnvironmentModule implements Module {
   }
 
   Module cloneCss() {
-    if (css.children.isEmpty) return this;
+    if (!transitivelyContainsCss) return this;
 
     var newCssAndExtensionStore = cloneCssStylesheet(css, extensionStore);
     return _EnvironmentModule._(

lib/src/environment.dart

@@ -5,7 +5,7 @@
 // DO NOT EDIT. This file was generated from async_environment.dart.
 // See tool/grind/synchronize.dart for details.
 //
-// Checksum: 88f81b417129a74e4eb776d518c8e019dbf2ec36
+// Checksum: 38c688423116df1e489aa6eafc16de1bf9bc2bf5
 //
 // ignore_for_file: unused_import
 
@@ -1022,7 +1022,7 @@ class _EnvironmentModule implements Module<Callable> {
   }
 
   Module<Callable> cloneCss() {
-    if (css.children.isEmpty) return this;
+    if (!transitivelyContainsCss) return this;
 
     var newCssAndExtensionStore = cloneCssStylesheet(css, extensionStore);
     return _EnvironmentModule._(

lib/src/functions/color.dart

@@ -120,9 +120,8 @@ final global = UnmodifiableListView([
 
   _function("adjust-hue", r"$color, $degrees", (arguments) {
     var color = arguments[0].assertColor("color");
-    var degrees = arguments[1].assertNumber("degrees");
-    _checkAngle(degrees, "degrees");
-    return color.changeHsl(hue: color.hue + degrees.value);
+    var degrees = _angleValue(arguments[1], "degrees");
+    return color.changeHsl(hue: color.hue + degrees);
   }),
 
   _function("lighten", r"$color, $amount", (arguments) {
@@ -220,7 +219,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass color module.
-final module = BuiltInModule("color", functions: [
+final module = BuiltInModule("color", functions: <Callable>[
   // ### RGB
   _red, _green, _blue, _mix,
 
@@ -453,9 +452,23 @@ SassColor _updateComponents(List<Value> arguments,
   /// [max] should be 255 for RGB channels, 1 for the alpha channel, and 100
   /// for saturation, lightness, whiteness, and blackness.
   double? getParam(String name, num max,
-      {bool checkPercent = false, bool assertPercent = false}) {
+      {bool checkPercent = false,
+      bool assertPercent = false,
+      bool checkUnitless = false}) {
     var number = keywords.remove(name)?.assertNumber(name);
     if (number == null) return null;
+    if (!scale && checkUnitless) {
+      if (number.hasUnits) {
+        warn(
+            "\$$name: Passing a number with unit ${number.unitString} is "
+            "deprecated.\n"
+            "\n"
+            "To preserve current behavior: ${number.unitSuggestion(name)}\n"
+            "\n"
+            "More info: https://sass-lang.com/d/function-units",
+            deprecation: true);
+      }
+    }
     if (!scale && checkPercent) _checkPercent(number, name);
     if (scale || assertPercent) number.assertUnit("%", name);
     if (scale) max = 100;
@@ -465,14 +478,14 @@ SassColor _updateComponents(List<Value> arguments,
             change ? 0 : -max, max, name, checkPercent ? '%' : '');
   }
 
-  var alpha = getParam("alpha", 1);
+  var alpha = getParam("alpha", 1, checkUnitless: true);
   var red = getParam("red", 255);
   var green = getParam("green", 255);
   var blue = getParam("blue", 255);
 
-  var hueNumber = scale ? null : keywords.remove("hue")?.assertNumber("hue");
-  if (hueNumber != null) _checkAngle(hueNumber, "hue");
-  var hue = hueNumber?.value;
+  var hue = scale
+      ? null
+      : keywords.remove("hue").andThen((hue) => _angleValue(hue, "hue"));
 
   var saturation = getParam("saturation", 100, checkPercent: true);
   var lightness = getParam("lightness", 100, checkPercent: true);
@@ -620,53 +633,37 @@ Value _hsl(String name, List<Value> arguments) {
     return _functionString(name, arguments);
   }
 
-  var hue = arguments[0].assertNumber("hue");
+  var hue = _angleValue(arguments[0], "hue");
   var saturation = arguments[1].assertNumber("saturation");
   var lightness = arguments[2].assertNumber("lightness");
 
-  _checkAngle(hue, "hue");
   _checkPercent(saturation, "saturation");
   _checkPercent(lightness, "lightness");
 
   return SassColor.hslInternal(
-      hue.value,
+      hue,
       saturation.value.clamp(0, 100),
       lightness.value.clamp(0, 100),
       alpha.andThen((alpha) =>
           _percentageOrUnitless(alpha.assertNumber("alpha"), 1, "alpha")),
       ColorFormat.hslFunction);
 }
 
-/// Prints a deprecation warning if [hue] has a unit other than `deg`.
-void _checkAngle(SassNumber angle, String name) {
-  if (!angle.hasUnits || angle.hasUnit('deg')) return;
-
-  var message = StringBuffer()
-    ..writeln("\$$name: Passing a unit other than deg ($angle) is deprecated.")
-    ..writeln();
-
-  if (angle.compatibleWithUnit('deg')) {
-    message
-      ..writeln(
-          "You're passing $angle, which is currently (incorrectly) converted "
-          "to ${SassNumber(angle.value, 'deg')}.")
-      ..writeln("Soon, it will instead be correctly converted to "
-          "${angle.coerce(['deg'], [])}.")
-      ..writeln();
-
-    var actualUnit = angle.numeratorUnits.first;
-    message
-      ..writeln("To preserve current behavior: \$$name * 1deg/1$actualUnit")
-      ..writeln("To migrate to new behavior: 0deg + \$$name")
-      ..writeln();
-  } else {
-    message
-      ..writeln("To preserve current behavior: \$$name${_removeUnits(angle)}")
-      ..writeln();
-  }
+/// Asserts that [angle] is a number and returns its value in degrees.
+///
+/// Prints a deprecation warning if [angle] has a non-angle unit.
+double _angleValue(Value angleValue, String name) {
+  var angle = angleValue.assertNumber(name);
+  if (angle.compatibleWithUnit('deg')) return angle.coerceValueToUnit('deg');
 
-  message.write("See https://sass-lang.com/d/color-units");
-  warn(message.toString(), deprecation: true);
+  warn(
+      "\$$name: Passing a unit other than deg ($angle) is deprecated.\n"
+      "\n"
+      "To preserve current behavior: ${angle.unitSuggestion(name)}\n"
+      "\n"
+      "See https://sass-lang.com/d/function-units",
+      deprecation: true);
+  return angle.value;
 }
 
 /// Prints a deprecation warning if [number] doesn't have unit `%`.
@@ -676,31 +673,24 @@ void _checkPercent(SassNumber number, String name) {
   warn(
       "\$$name: Passing a number without unit % ($number) is deprecated.\n"
       "\n"
-      "To preserve current behavior: \$$name${_removeUnits(number)} * 1%",
+      "To preserve current behavior: ${number.unitSuggestion(name, '%')}\n"
+      "\n"
+      "More info: https://sass-lang.com/d/function-units",
       deprecation: true);
 }
 
-/// Returns the right-hand side of an expression that would remove all units
-/// from `$number` but leaves the value the same.
-///
-/// Used for constructing deprecation messages.
-String _removeUnits(SassNumber number) =>
-    number.denominatorUnits.map((unit) => " * 1$unit").join() +
-    number.numeratorUnits.map((unit) => " / 1$unit").join();
-
 /// Create an HWB color from the given [arguments].
 Value _hwb(List<Value> arguments) {
   var alpha = arguments.length > 3 ? arguments[3] : null;
-  var hue = arguments[0].assertNumber("hue");
+  var hue = _angleValue(arguments[0], "hue");
   var whiteness = arguments[1].assertNumber("whiteness");
   var blackness = arguments[2].assertNumber("blackness");
 
-  _checkAngle(hue, "hue");
   whiteness.assertUnit("%", "whiteness");
   blackness.assertUnit("%", "blackness");
 
   return SassColor.hwb(
-      hue.value,
+      hue,
       whiteness.valueInRange(0, 100, "whiteness"),
       blackness.valueInRange(0, 100, "blackness"),
       alpha.andThen((alpha) =>
@@ -805,6 +795,8 @@ double _percentageOrUnitless(SassNumber number, num max, String name) {
 
 /// Returns [color1] and [color2], mixed together and weighted by [weight].
 SassColor _mixColors(SassColor color1, SassColor color2, SassNumber weight) {
+  _checkPercent(weight, 'weight');
+
   // This algorithm factors in both the user-provided weight (w) and the
   // difference between the alpha values of the two colors (a) to decide how
   // to perform the weighted average of the two RGB values.

lib/src/functions/list.dart

@@ -18,7 +18,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass list module.
-final module = BuiltInModule("list", functions: [
+final module = BuiltInModule("list", functions: <Callable>[
   _length, _nth, _setNth, _join, _append, _zip, _index, _isBracketed, //
   _separator, _slash
 ]);

lib/src/functions/map.dart

@@ -23,7 +23,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass map module.
-final module = BuiltInModule("map", functions: [
+final module = BuiltInModule("map", functions: <Callable>[
   _get,
   _set,
   _merge,

lib/src/functions/math.dart

@@ -22,7 +22,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass math module.
-final module = BuiltInModule("math", functions: [
+final module = BuiltInModule("math", functions: <Callable>[
   _abs, _acos, _asin, _atan, _atan2, _ceil, _clamp, _cos, _compatible, //
   _floor, _hypot, _isUnitless, _log, _max, _min, _percentage, _pow, //
   _randomFunction, _round, _sin, _sqrt, _tan, _unit, _div
@@ -251,17 +251,17 @@ final _randomFunction = _function("random", r"$limit: null", (arguments) {
 
   if (limit.hasUnits) {
     warn(
-      "math.random() will no longer ignore \$limit units ($limit) in a "
-      "future release.\n"
-      "\n"
-      "Recommendation: "
-      "math.random(math.div(\$limit, 1${limit.unitString})) * 1${limit.unitString}\n"
-      "\n"
-      "To preserve current behavior: "
-      "math.random(math.div(\$limit, 1${limit.unitString}))\n"
-      "\n"
-      "More info: https://sass-lang.com/d/random-with-units",
-    );
+        "math.random() will no longer ignore \$limit units ($limit) in a "
+        "future release.\n"
+        "\n"
+        "Recommendation: "
+        "math.random(math.div(\$limit, 1${limit.unitString})) * 1${limit.unitString}\n"
+        "\n"
+        "To preserve current behavior: "
+        "math.random(math.div(\$limit, 1${limit.unitString}))\n"
+        "\n"
+        "More info: https://sass-lang.com/d/function-units",
+        deprecation: true);
   }
 
   var limitScalar = limit.assertInt("limit");

lib/src/functions/selector.dart

@@ -27,7 +27,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass selector module.
-final module = BuiltInModule("selector", functions: [
+final module = BuiltInModule("selector", functions: <Callable>[
   _isSuperselector,
   _simpleSelectors,
   _parse,

lib/src/functions/string.dart

@@ -29,7 +29,7 @@ final global = UnmodifiableListView([
 ]);
 
 /// The Sass string module.
-final module = BuiltInModule("string", functions: [
+final module = BuiltInModule("string", functions: <Callable>[
   _unquote, _quote, _toUpperCase, _toLowerCase, _length, _insert, _index, //
   _slice, _uniqueId,
 ]);

lib/src/importer/legacy_node/implementation.dart

@@ -183,6 +183,11 @@ class NodeImporter {
 
     var file = value.file;
     var contents = value.contents;
+    if (contents != null && !isJsString(contents)) {
+      jsThrow(ArgumentError.value(contents, 'contents',
+          'must be a string but was: ${jsType(contents)}'));
+    }
+
     if (file == null) {
       return Tuple2(contents ?? '', url);
     } else if (contents != null) {

lib/src/importer/node_to_dart/async.dart

@@ -43,6 +43,11 @@ class NodeToDartAsyncImporter extends AsyncImporter {
 
     result as NodeImporterResult;
     var contents = result.contents;
+    if (!isJsString(contents)) {
+      jsThrow(ArgumentError.value(contents, 'contents',
+          'must be a string but was: ${jsType(contents)}'));
+    }
+
     var syntax = result.syntax;
     if (contents == null || syntax == null) {
       jsThrow(JsError("The load() function must return an object with contents "

lib/src/importer/node_to_dart/sync.dart

@@ -48,6 +48,11 @@ class NodeToDartImporter extends Importer {
 
     result as NodeImporterResult;
     var contents = result.contents;
+    if (!isJsString(contents)) {
+      jsThrow(ArgumentError.value(contents, 'contents',
+          'must be a string but was: ${jsType(contents)}'));
+    }
+
     var syntax = result.syntax;
     if (contents == null || syntax == null) {
       jsThrow(JsError("The load() function must return an object with contents "