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,28 @@ 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}
+Object simplify(Object value) => switch (value) {
+      SassCalculation() => switch ((
+          // Match against...
+          value.name, // ...the calculation name
+          value.arguments.map(simplify).toList() // ...and simplified arguments
+        )) {
+          ('calc', [var first, ...]) => first,
+          ('clamp', [var min, var value, var max]) =>
+            SassCalculation.clamp(min, value, max),
+          ('clamp', _) =>
+            throw ArgumentError('clamp() requires exactly 3 arguments.'),
+          ('min', var args) => SassCalculation.min(args),
+          ('max', var args) => SassCalculation.max(args),
+          (var name, var args) => SassCalculation.unsimplified(name, args)
+        },
+      CalculationOperation() => SassCalculation.operate(
+          value.operator, simplify(value.left), simplify(value.right)),
+      _ => value,
+    };
+
 /// Parses `functions` from [record] into a list of [Callable]s or
 /// [AsyncCallable]s.
 ///
@@ -238,7 +260,8 @@ List<AsyncCallable> _parseFunctions(Object? functions, {bool asynch = false}) {
     if (!asynch) {
       late Callable callable;
       callable = Callable.fromSignature(signature, (arguments) {
-        var result = (callback as Function)(toJSArray(arguments));
+        var result =
+            simplify((callback as Function)(toJSArray(arguments)) as Object);
         if (result is Value) return result;
         if (isPromise(result)) {
           throw 'Invalid return value for custom function '
@@ -259,7 +282,8 @@ List<AsyncCallable> _parseFunctions(Object? functions, {bool asynch = false}) {
           result = await promiseToFuture<Object>(result as Promise);
         }
 
-        if (result is Value) return result;
+        var simplified = simplify(result as Object);
+        if (simplified is Value) return simplified;
         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,128 @@
+// 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) {
+  if (arg is! SassNumber &&
+      arg is! SassString &&
+      arg is! SassCalculation &&
+      arg is! CalculationOperation &&
+      arg is! CalculationInterpolation) {
+    jsThrow(JsError('Argument `$arg` must be one of '
+        'SassNumber, SassString, SassCalculation, CalculationOperation, '
+        'CalculationInterpolation'));
+  }
+  if (arg is SassString && arg.hasQuotes) {
+    jsThrow(JsError('Argument `$arg` must be unquoted SassString'));
+  }
+}
+
+/// Check that [arg] is an unquoted string or interpolation
+bool isValidClampArg(Object? arg) => ((arg is CalculationInterpolation) ||
+    (arg is SassString && !arg.hasQuotes));
+
+/// 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 && !isValidClampArg(min)) ||
+          (max == null) && !([min, value]).any(isValidClampArg)) {
+        jsThrow(JsError('Expected at least one SassString or '
+            'CalculationInterpolation in `${[
+          min,
+          value,
+          max
+        ].whereNotNull()}`'));
+      }
+      [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);
+    assertCalculationValue(right);
+    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',