[Function Name] Implement changes (#2731)

See sass/sass#4048

Author: nex3

CHANGELOG.md

@@ -1,3 +1,32 @@
+## 1.99.0
+
+* User-defined functions named `calc` or `clamp` are no longer forbidden. If
+  such a function exists without a namespace in the current module, it will be
+  used instead of the built-in `calc()` or `clamp()` function.
+
+* User-defined functions whose names begin with `-` and end with `-expression`,
+  `-url`, `-and`, `-or`, or `-not` are no longer forbidden. These were
+  originally intended to match vendor prefixes, but in practice no vendor
+  prefixes for these functions ever existed in real browsers.
+
+* User-defined functions named `EXPRESSION`, `URL`, and `ELEMENT`, those that
+  begin with `-` and end with `-ELEMENT`, as well as the same names with some
+  lowercase letters are now deprecated, These are names conflict with plain CSS
+  functions that have special syntax.
+
+  See [the Sass website](https://sass-lang.com/d/function-name) for details.
+
+* In a future release, calls to functions whose names begin with `-` and end
+  with `-expression` and `-url` will no longer have special parsing. For now,
+  these calls are deprecated if their behavior will change in the future.
+
+  See [the Sass website](https://sass-lang.com/d/function-name) for details.
+
+* Calls to functions whose names begin with `-` and end with `-progid:...` are
+  deprecated.
+
+  See [the Sass website](https://sass-lang.com/d/function-name) for details.
+
 ## 1.98.0
 
 ### Command-Line Interface

lib/src/ast/sass/expression.dart

@@ -8,6 +8,7 @@ import '../../exception.dart';
 import '../../parse/scss.dart';
 import '../../visitor/interface/expression.dart';
 import '../../visitor/is_calculation_safe.dart';
+import '../../visitor/is_plain_css.dart';
 import '../../visitor/source_interpolation.dart';
 import '../sass.dart';
 
@@ -48,4 +49,12 @@ abstract class Expression implements SassNode {
   /// Throws a [SassFormatException] if parsing fails.
   factory Expression.parse(String contents, {Object? url}) =>
       ScssParser(contents, url: url).parseExpression().$1;
+
+  /// Whether this expression is valid plain CSS that will produce the same
+  /// result as it would in Sass
+  ///
+  /// If [allowInterpolation] is true, interpolated expressions are allowed as
+  /// an exception, even if they contain SassScript.
+  bool isPlainCss({bool allowInterpolation = false}) =>
+      accept(IsPlainCssVisitor(allowInterpolation: allowInterpolation));
 }

lib/src/ast/sass/expression/string.dart

@@ -52,7 +52,7 @@ final class StringExpression extends Expression {
 
   /// Interpolation that, when evaluated, produces the syntax of this string.
   ///
-  /// Unlike [text], his doesn't resolve escapes and does include quotes for
+  /// Unlike [text], this doesn't resolve escapes and does include quotes for
   /// quoted strings.
   ///
   /// If [static] is true, this escapes any `#{` sequences in the string. If

lib/src/deprecation.dart

@@ -15,7 +15,7 @@ enum Deprecation {
   // DO NOT EDIT. This section was generated from the language repo.
   // See tool/grind/generate_deprecations.dart for details.
   //
-  // Checksum: 6fc524360d067b73c243c666e27a9a9ea7e08841
+  // Checksum: 916d5fa5139e08988de6e29f7d8f7fab5e973b31
 
   /// Deprecation for passing a string directly to meta.call().
   callString('call-string',
@@ -151,6 +151,11 @@ enum Deprecation {
       deprecatedIn: '1.95.0',
       description: 'The Sass if(\$condition, \$if-true, \$if-false) function.'),
 
+  /// Deprecation for uppercase reserved function names.
+  functionName('function-name',
+      deprecatedIn: '1.98.0',
+      description: 'Uppercase reserved function names.'),
+
   // END AUTOGENERATED CODE
 
   /// Used for deprecations coming from user-authored code.

lib/src/parse/stylesheet.dart

@@ -962,6 +962,25 @@ abstract class StylesheetParser extends Parser {
           spanFrom(beforeName));
     }
 
+    if (switch (name) {
+      "expression" || "url" || "and" || "or" || "not" => true,
+      _ => unvendor(name) == "element"
+    }) {
+      error("Invalid function name.", spanFrom(beforeName));
+    } else if (switch (name.toLowerCase()) {
+      "expression" || "url" => true,
+      var name => unvendor(name) == "element"
+    }) {
+      warnings.add((
+        deprecation: Deprecation.functionName,
+        message: "Custom functions with this name are deprecated and will be "
+            "removed in a future\n"
+            "release. Please choose a different name.\n"
+            "More info: https://sass-lang.com/d/function-name",
+        span: spanFrom(beforeName)
+      ));
+    }
+
     whitespace(consumeNewlines: true);
     var parameters = _parameterList();
 
@@ -977,18 +996,6 @@ abstract class StylesheetParser extends Parser {
       );
     }
 
-    if (unvendor(name)
-        case "calc" ||
-            "element" ||
-            "expression" ||
-            "url" ||
-            "and" ||
-            "or" ||
-            "not" ||
-            "clamp") {
-      error("Invalid function name.", spanFrom(start));
-    }
-
     whitespace(consumeNewlines: false);
     return _withChildren(
       _functionChild,
@@ -3324,9 +3331,54 @@ abstract class StylesheetParser extends Parser {
         ..writeCharCode($lparen);
     } else {
       var normalized = unvendor(name);
+      var vendored = normalized != name;
       switch (normalized) {
-        case "calc" when normalized != name && scanner.scanChar($lparen):
-        case "element" || "expression" when scanner.scanChar($lparen):
+        case "expression" when vendored && scanner.scanChar($lparen):
+          buffer = InterpolationBuffer()
+            ..write(name)
+            ..writeCharCode($lparen);
+
+          var beforeArg = scanner.state;
+          var invalidSassScript = false;
+          var nonCssSassScript = false;
+          try {
+            var argument = _expression();
+            nonCssSassScript = !argument.isPlainCss(allowInterpolation: true);
+          } on StringScannerException {
+            invalidSassScript = true;
+          }
+          scanner.state = beforeArg;
+
+          var value = _interpolatedDeclarationValue(allowEmpty: true);
+          buffer.addInterpolation(value);
+          scanner.expectChar($rparen);
+          buffer.writeCharCode($rparen);
+
+          if (invalidSassScript || nonCssSassScript) {
+            var suggestion =
+                StringExpression(value, quotes: true).asInterpolation();
+            warnings.add((
+              deprecation: Deprecation.functionName,
+              message: "Vendor-prefixed $normalized() functions will no longer "
+                      "have special parsing in a future release of Dart Sass. "
+                      "Once that happens, this argument will " +
+                  (invalidSassScript
+                      ? "be parsed as SassScript. "
+                      : "no longer be valid syntax. ") +
+                  "To preserve current behavior:\n"
+                      "\n"
+                      "$name(#{$suggestion})\n"
+                      "\n"
+                      "More info: https://sass-lang.com/d/function-name",
+              span: spanFrom(start)
+            ));
+          }
+
+          return StringExpression(buffer.interpolation(spanFrom(start)));
+
+        case "calc" when vendored && scanner.scanChar($lparen):
+        case "expression" when !vendored && scanner.scanChar($lparen):
+        case "element" when scanner.scanChar($lparen):
           buffer = InterpolationBuffer()
             ..write(name)
             ..writeCharCode($lparen);
@@ -3343,9 +3395,36 @@ abstract class StylesheetParser extends Parser {
           scanner.expectChar($lparen);
           buffer.writeCharCode($lparen);
 
+          buffer.addInterpolation(
+              _interpolatedDeclarationValue(allowEmpty: true));
+          scanner.expectChar($rparen);
+          buffer.writeCharCode($rparen);
+
+          if (vendored) {
+            var suggestion = StringExpression(
+                    buffer.interpolation(spanFrom(start)),
+                    quotes: true)
+                .asInterpolation();
+            warnings.add((
+              deprecation: Deprecation.functionName,
+              message:
+                  "Vendor-prefixed progid:...() functions will no longer be "
+                  "supported in a future release of Dart Sass. To preserve "
+                  "current behavior:\n"
+                  "\n"
+                  "#{$suggestion}\n"
+                  "\n"
+                  "More info: https://sass-lang.com/d/function-name",
+              span: spanFrom(start)
+            ));
+          }
+
+          return StringExpression(buffer.interpolation(spanFrom(start)));
+
         case "url":
           return _tryUrlContents(
             start,
+            vendored: vendored,
           ).andThen((contents) => StringExpression(contents));
 
         case _:
@@ -3363,13 +3442,28 @@ abstract class StylesheetParser extends Parser {
   /// Like [_urlContents], but returns `null` if the URL fails to parse.
   ///
   /// [start] is the position before the beginning of the name. [name] is the
-  /// function's name; it defaults to `"url"`.
-  Interpolation? _tryUrlContents(LineScannerState start, {String? name}) {
+  /// function's name; it defaults to `"url"`. [vendored] is true if this is
+  /// being parsed in an expression context as a deprecated vendor-prefixed
+  /// `url()` expression.
+  Interpolation? _tryUrlContents(LineScannerState start,
+      {String? name, bool vendored = false}) {
     // NOTE: this logic is largely duplicated in Parser.tryUrl. Most changes
     // here should be mirrored there.
 
     var beginningOfContents = scanner.state;
     if (!scanner.scanChar($lparen)) return null;
+
+    var invalidSassScript = false;
+    if (vendored) {
+      var beforeArg = scanner.state;
+      try {
+        _expression();
+      } on StringScannerException {
+        invalidSassScript = true;
+      }
+      scanner.state = beforeArg;
+    }
+
     whitespaceWithoutComments(consumeNewlines: true);
 
     // Match Ruby Sass's behavior: parse a raw URL() if possible, and if not
@@ -3391,8 +3485,6 @@ abstract class StylesheetParser extends Parser {
               $percent ||
               $ampersand ||
               $hash ||
-              // dart-lang/sdk#52740
-              // ignore: non_constant_relational_pattern_expression
               (>= $asterisk && <= $tilde) ||
               >= 0x80:
           buffer.writeCharCode(scanner.readChar());
@@ -3401,6 +3493,26 @@ abstract class StylesheetParser extends Parser {
           if (scanner.peekChar() != $rparen) break loop;
         case $rparen:
           buffer.writeCharCode(scanner.readChar());
+
+          if (vendored && invalidSassScript) {
+            var suggestion = StringExpression(
+                    buffer.interpolation(spanFrom(start)),
+                    quotes: true)
+                .asInterpolation();
+            warnings.add((
+              deprecation: Deprecation.functionName,
+              message: "Vendor-prefixed url() functions will no longer have "
+                  "special parsing in a future release of Dart Sass. Once "
+                  "that happens, this argument will be parsed as SassScript. "
+                  "To preserve current behavior:\n"
+                  "\n"
+                  "$name(#{$suggestion})\n"
+                  "\n"
+                  "More info: https://sass-lang.com/d/function-name",
+              span: spanFrom(start)
+            ));
+          }
+
           return buffer.interpolation(spanFrom(start));
         case _:
           break loop;

lib/src/visitor/is_plain_css.dart

@@ -0,0 +1,98 @@
+// Copyright 2026 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import '../ast/sass.dart';
+import 'interface/expression.dart';
+import 'interface/if_condition_expression.dart';
+
+// We could use [AstSearchVisitor] to implement this more tersely, but that
+// would default to returning `true` if we added a new expression type and
+// forgot to update this class.
+
+/// A visitor that determines whether an expression is valid plain CSS that will
+/// produce the same result as it would in Sass.
+///
+/// This should be used through [Expression.isPlainCss].
+class IsPlainCssVisitor
+    implements ExpressionVisitor<bool>, IfConditionExpressionVisitor<bool> {
+  /// Whether to allow interpolation to as an exception to allowing plain CSS.
+  final bool _allowInterpolation;
+
+  /// If [allowInterpolation] is true, interpolated expressions are allowed as
+  /// an exception, even if they contain SassScript.
+  const IsPlainCssVisitor({bool allowInterpolation = false})
+      : _allowInterpolation = allowInterpolation;
+
+  bool visitBinaryOperationExpression(BinaryOperationExpression node) => false;
+
+  bool visitBooleanExpression(BooleanExpression node) => false;
+
+  bool visitColorExpression(ColorExpression node) => true;
+
+  bool visitFunctionExpression(FunctionExpression node) =>
+      node.namespace == null && _visitArgumentList(node.arguments);
+
+  bool visitIfExpression(IfExpression node) =>
+      node.branches.every((pair) => switch (pair) {
+            (var condition?, var branch) =>
+              condition.accept(this) && branch.accept(this),
+            (_, var branch) => branch.accept(this),
+          });
+
+  bool visitInterpolatedFunctionExpression(
+    InterpolatedFunctionExpression node,
+  ) =>
+      _allowInterpolation && _visitArgumentList(node.arguments);
+
+  bool visitLegacyIfExpression(LegacyIfExpression node) => false;
+
+  bool visitListExpression(ListExpression node) =>
+      (node.contents.isNotEmpty || node.hasBrackets) &&
+      node.contents.every((element) => element.accept(this));
+
+  bool visitMapExpression(MapExpression node) => false;
+
+  bool visitNullExpression(NullExpression node) => false;
+
+  bool visitNumberExpression(NumberExpression node) => true;
+
+  bool visitParenthesizedExpression(ParenthesizedExpression node) =>
+      node.expression.accept(this);
+
+  bool visitSelectorExpression(SelectorExpression node) => false;
+
+  bool visitStringExpression(StringExpression node) =>
+      _allowInterpolation || node.text.isPlain;
+
+  bool visitSupportsExpression(SupportsExpression node) => false;
+
+  bool visitUnaryOperationExpression(UnaryOperationExpression node) => false;
+
+  bool visitValueExpression(ValueExpression node) => false;
+
+  bool visitVariableExpression(VariableExpression node) => false;
+
+  bool visitIfConditionParenthesized(IfConditionParenthesized node) =>
+      node.expression.accept(this);
+
+  bool visitIfConditionNegation(IfConditionNegation node) =>
+      node.expression.accept(this);
+
+  bool visitIfConditionOperation(IfConditionOperation node) =>
+      node.expressions.every((expression) => expression.accept(this));
+
+  bool visitIfConditionFunction(IfConditionFunction node) =>
+      _allowInterpolation || (node.name.isPlain && node.arguments.isPlain);
+
+  bool visitIfConditionSass(IfConditionSass node) => false;
+
+  bool visitIfConditionRaw(IfConditionRaw node) =>
+      _allowInterpolation || node.text.isPlain;
+
+  /// Returns whether [arguments] contains only plain CSS.
+  bool _visitArgumentList(ArgumentList node) =>
+      node.named.isEmpty &&
+      node.rest == null &&
+      node.positional.every((argument) => argument.accept(this));
+}

pkg/sass-parser/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.44
+
+* No user-visible changes.
+
 ## 0.4.43
 
 * No user-visible changes.