Expose calculations in JS API

lib/src/node.dart

@@ -27,6 +27,9 @@ void main() {
   exports.Value = valueClass;
   exports.SassBoolean = booleanClass;
   exports.SassArgumentList = argumentListClass;
+  exports.SassCalculation = calculationClass;
+  exports.CalculationOperation = calculationOperationClass;
+  exports.CalculationInterpolation = calculationInterpolationClass;
   exports.SassColor = colorClass;
   exports.SassFunction = functionClass;
   exports.SassList = listClass;

lib/src/node/compile.dart

@@ -225,6 +225,32 @@ Importer _parseImporter(Object? importer) {
   }
 }
 
+/// Implements the simplification algorithm for custom function return values.
+/// {@link https://github.com/sass/sass/blob/main/spec/types/calculation.md#simplifying-a-calculationvalue}
+dynamic simplify(dynamic value) {
+  if (value is SassCalculation) {
+    var simplifiedArgs = value.arguments.map(simplify).toList().cast<Object>();
+    if (value.name == 'calc') {
+      return simplifiedArgs[0];
+    }
+    if (value.name == 'clamp') {
+      return simplify(Function.apply(SassCalculation.clamp, simplifiedArgs));
+    }
+    if (value.name == 'min') {
+      return simplify(Function.apply(SassCalculation.min, [simplifiedArgs]));
+    }
+    if (value.name == 'max') {
+      return simplify(Function.apply(SassCalculation.max, [simplifiedArgs]));
+    }
+    return SassCalculation.unsimplified(value.name, simplifiedArgs);
+  }
+  if (value is CalculationOperation) {
+    return simplify(SassCalculation.operate(value.operator,
+        simplify(value.left) as Object, simplify(value.right) as Object));
+  }
+  return value;
+}
+
 /// Parses `functions` from [record] into a list of [Callable]s or
 /// [AsyncCallable]s.
 ///
@@ -239,6 +265,7 @@ List<AsyncCallable> _parseFunctions(Object? functions, {bool asynch = false}) {
       late Callable callable;
       callable = Callable.fromSignature(signature, (arguments) {
         var result = (callback as Function)(toJSArray(arguments));
+        result = simplify(result);
         if (result is Value) return result;
         if (isPromise(result)) {
           throw 'Invalid return value for custom function '
@@ -259,6 +286,7 @@ List<AsyncCallable> _parseFunctions(Object? functions, {bool asynch = false}) {
           result = await promiseToFuture<Object>(result as Promise);
         }
 
+        result = simplify(result);
         if (result is Value) return result;
         throw 'Invalid return value for custom function '
             '"${callable.name}": $result is not a sass.Value.';

lib/src/node/exports.dart

@@ -26,6 +26,9 @@ class Exports {
   // Value APIs
   external set Value(JSClass function);
   external set SassArgumentList(JSClass function);
+  external set SassCalculation(JSClass function);
+  external set CalculationOperation(JSClass function);
+  external set CalculationInterpolation(JSClass function);
   external set SassBoolean(JSClass function);
   external set SassColor(JSClass function);
   external set SassFunction(JSClass function);

lib/src/node/reflection.dart

@@ -76,6 +76,16 @@ extension JSClassExtension on JSClass {
         allowInteropCaptureThis((Object self, _, __, [___]) => inspect(self)));
   }
 
+  /// Defines a static method with the given [name] and [body].
+  void defineStaticMethod(String name, Function body) {
+    setProperty(this, name, allowInteropNamed(name, body));
+  }
+
+  /// A shorthand for calling [defineStaticMethod] multiple times.
+  void defineStaticMethods(Map<String, Function> methods) {
+    methods.forEach(defineStaticMethod);
+  }
+
   /// Defines a method with the given [name] and [body].
   ///
   /// The [body] should take an initial `self` parameter, representing the

lib/src/node/value.dart

@@ -10,6 +10,7 @@ import 'reflection.dart';
 
 export 'value/argument_list.dart';
 export 'value/boolean.dart';
+export 'value/calculation.dart';
 export 'value/color.dart';
 export 'value/function.dart';
 export 'value/list.dart';
@@ -36,6 +37,8 @@ final JSClass valueClass = () {
     'get': (Value self, num index) =>
         index < 1 && index >= -1 ? self : undefined,
     'assertBoolean': (Value self, [String? name]) => self.assertBoolean(name),
+    'assertCalculation': (Value self, [String? name]) =>
+        self.assertCalculation(name),
     'assertColor': (Value self, [String? name]) => self.assertColor(name),
     'assertFunction': (Value self, [String? name]) => self.assertFunction(name),
     'assertMap': (Value self, [String? name]) => self.assertMap(name),

lib/src/node/value/calculation.dart

@@ -0,0 +1,134 @@
+// Copyright 2023 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 'package:collection/collection.dart';
+import 'package:node_interop/js.dart';
+import 'package:sass/src/node/immutable.dart';
+import 'package:sass/src/node/utils.dart';
+
+import '../../value.dart';
+import '../reflection.dart';
+
+/// Check that [arg] is a valid argument to a calculation function.
+void assertCalculationValue(Object arg, {bool checkUnquoted = true}) {
+  if (arg is! SassNumber &&
+      arg is! SassString &&
+      arg is! SassCalculation &&
+      arg is! CalculationOperation &&
+      arg is! CalculationInterpolation) {
+    jsThrow(JsError('Argument must be one of '
+        'SassNumber, SassString, SassCalculation, CalculationOperation, '
+        'CalculationInterpolation'));
+  }
+  if (checkUnquoted && arg is SassString && arg.hasQuotes) {
+    jsThrow(JsError('Argument must be unquoted SassString'));
+  }
+  if (arg is CalculationOperation) {
+    assertCalculationValue(arg.left, checkUnquoted: checkUnquoted);
+    assertCalculationValue(arg.right, checkUnquoted: checkUnquoted);
+  }
+}
+
+/// Check that [arg] is an unquoted string or interpolation
+void assertUnquotedStringOrInterpolation(Object arg) {
+  if ((arg is! SassString && arg is! CalculationInterpolation) ||
+      (arg is SassString && arg.hasQuotes)) {
+    jsThrow(JsError(
+        'Argument must be an unquoted SassString or CalculationInterpolation'));
+  }
+}
+
+/// The JavaScript `SassCalculation` class.
+final JSClass calculationClass = () {
+  var jsClass =
+      createJSClass('sass.SassCalculation', (Object self, [Object? _]) {
+    jsThrow(JsError("new sass.SassCalculation() isn't allowed"));
+  });
+
+  jsClass.defineStaticMethods({
+    'calc': (Object argument) {
+      assertCalculationValue(argument);
+      return SassCalculation.unsimplified('calc', [argument]);
+    },
+    'min': (Object arguments) {
+      var argList = jsToDartList(arguments).cast<Object>();
+      argList.forEach(assertCalculationValue);
+      return SassCalculation.unsimplified('min', argList);
+    },
+    'max': (Object arguments) {
+      var argList = jsToDartList(arguments).cast<Object>();
+      argList.forEach(assertCalculationValue);
+      return SassCalculation.unsimplified('max', argList);
+    },
+    'clamp': (Object min, [Object? value, Object? max]) {
+      if (value == null) {
+        assertUnquotedStringOrInterpolation(min);
+      } else if (max == null) {
+        assertUnquotedStringOrInterpolation(min);
+        assertUnquotedStringOrInterpolation(value);
+      }
+      [min, value, max].whereNotNull().forEach(assertCalculationValue);
+      return SassCalculation.unsimplified(
+          'clamp', [min, value, max].whereNotNull());
+    }
+  });
+
+  jsClass.defineMethods({
+    'assertCalculation': (SassCalculation self, [String? name]) => self,
+  });
+
+  jsClass.defineGetters({
+    // The `name` getter is included by default by `createJSClass`
+    'arguments': (SassCalculation self) => ImmutableList(self.arguments),
+  });
+
+  getJSClass(SassCalculation.unsimplified('calc', [SassNumber(1)]))
+      .injectSuperclass(jsClass);
+  return jsClass;
+}();
+
+/// The JavaScript CalculationOperation class
+final JSClass calculationOperationClass = () {
+  var jsClass = createJSClass('sass.CalculationOperation',
+      (Object self, String strOperator, Object left, Object right) {
+    var operator = CalculationOperator.values
+        .firstWhereOrNull((value) => value.operator == strOperator);
+    if (operator == null) {
+      jsThrow(JsError('Invalid operator: $strOperator'));
+    }
+    assertCalculationValue(left, checkUnquoted: false);
+    assertCalculationValue(right, checkUnquoted: false);
+    return SassCalculation.operateInternal(operator, left, right,
+        inMinMax: false, simplify: false);
+  });
+
+  jsClass.defineMethods({
+    'equals': (CalculationOperation self, Object other) => self == other,
+    'hashCode': (CalculationOperation self) => self.hashCode,
+  });
+
+  jsClass.defineGetters({
+    'operator': (CalculationOperation self) => self.operator.operator,
+  });
+
+  getJSClass(SassCalculation.operateInternal(
+          CalculationOperator.plus, SassNumber(1), SassNumber(1),
+          inMinMax: false, simplify: false))
+      .injectSuperclass(jsClass);
+  return jsClass;
+}();
+
+/// The JavaScript CalculationInterpolation class
+final JSClass calculationInterpolationClass = () {
+  var jsClass = createJSClass('sass.CalculationInterpolation',
+      (Object self, String value) => CalculationInterpolation(value));
+
+  jsClass.defineMethods({
+    'equals': (CalculationInterpolation self, Object other) => self == other,
+    'hashCode': (CalculationInterpolation self) => self.hashCode,
+  });
+
+  getJSClass(CalculationInterpolation('')).injectSuperclass(jsClass);
+  return jsClass;
+}();

lib/src/value/calculation.dart

@@ -329,7 +329,13 @@ class SassCalculation extends Value {
 @sealed
 class CalculationOperation {
   /// The operator.
-  final CalculationOperator operator;
+  CalculationOperator get operator {
+    // We use a getter to allow overriding the logic in the JS API
+    // implementation
+    return _operator;
+  }
+
+  final CalculationOperator _operator;
 
   /// The left-hand operand.
   ///
@@ -343,7 +349,7 @@ class CalculationOperation {
   /// [SassString], a [CalculationOperation], or a [CalculationInterpolation].
   final Object right;
 
-  CalculationOperation._(this.operator, this.left, this.right);
+  CalculationOperation._(this._operator, this.left, this.right);
 
   bool operator ==(Object other) =>
       other is CalculationOperation &&

tool/grind.dart

@@ -54,6 +54,9 @@ void main(List<String> args) {
     'Logger',
     'SassArgumentList',
     'SassBoolean',
+    'SassCalculation',
+    'CalculationOperation',
+    'CalculationInterpolation',
     'SassColor',
     'SassFunction',
     'SassList',