implement first class mixins

lib/src/callable/async_built_in.dart

@@ -26,6 +26,8 @@ class AsyncBuiltInCallable implements AsyncCallable {
   /// The callback to run when executing this callable.
   final Callback _callback;
 
+  bool hasContent = false;
+
   /// Creates a function with a single [arguments] declaration and a single
   /// [callback].
   ///
@@ -52,7 +54,7 @@ class AsyncBuiltInCallable implements AsyncCallable {
   /// defined.
   AsyncBuiltInCallable.mixin(String name, String arguments,
       FutureOr<void> callback(List<Value> arguments),
-      {Object? url})
+      {Object? url, bool hasContent = false})
       : this.parsed(name,
             ArgumentDeclaration.parse('@mixin $name($arguments) {', url: url),
             (arguments) async {
@@ -62,11 +64,12 @@ class AsyncBuiltInCallable implements AsyncCallable {
           // quickly so it's easier to just return Sass's `null` for mixins and
           // simply ignore it at the call site.
           return sassNull;
-        });
+        }, hasContent: hasContent);
 
   /// Creates a callable with a single [arguments] declaration and a single
   /// [callback].
-  AsyncBuiltInCallable.parsed(this.name, this._arguments, this._callback);
+  AsyncBuiltInCallable.parsed(this.name, this._arguments, this._callback,
+      {this.hasContent = false});
 
   /// Returns the argument declaration and Dart callback for the given
   /// positional and named arguments.

lib/src/callable/built_in.dart

@@ -21,6 +21,8 @@ final class BuiltInCallable implements Callable, AsyncBuiltInCallable {
   /// The overloads declared for this callable.
   final List<(ArgumentDeclaration, Callback)> _overloads;
 
+  bool hasContent = false;
+
   /// Creates a function with a single [arguments] declaration and a single
   /// [callback].
   ///
@@ -48,18 +50,19 @@ final class BuiltInCallable implements Callable, AsyncBuiltInCallable {
   /// defined.
   BuiltInCallable.mixin(
       String name, String arguments, void callback(List<Value> arguments),
-      {Object? url})
+      {Object? url, bool hasContent = false})
       : this.parsed(name,
             ArgumentDeclaration.parse('@mixin $name($arguments) {', url: url),
             (arguments) {
           callback(arguments);
           return sassNull;
-        });
+        }, hasContent: hasContent);
 
   /// Creates a callable with a single [arguments] declaration and a single
   /// [callback].
   BuiltInCallable.parsed(this.name, ArgumentDeclaration arguments,
-      Value callback(List<Value> arguments))
+      Value callback(List<Value> arguments),
+      {this.hasContent = false})
       : _overloads = [(arguments, callback)];
 
   /// Creates a function with multiple implementations.

lib/src/functions/meta.dart

@@ -6,6 +6,7 @@ import 'dart:collection';
 
 import 'package:collection/collection.dart';
 
+import '../ast/sass/statement/mixin_rule.dart';
 import '../callable.dart';
 import '../util/map.dart';
 import '../value.dart';
@@ -45,6 +46,7 @@ final global = UnmodifiableListView([
             sassNull => "null",
             SassNumber() => "number",
             SassFunction() => "function",
+            SassMixin() => "mixin",
             SassCalculation() => "calculation",
             SassString() => "string",
             _ => throw "[BUG] Unknown value type ${arguments[0]}"
@@ -77,6 +79,18 @@ final local = UnmodifiableListView([
             ? argument
             : SassString(argument.toString(), quotes: false)),
         ListSeparator.comma);
+  }),
+  _function("accepts-content", r"$mixin", (arguments) {
+    var mixin = arguments[0].assertMixin("mixin");
+    bool acceptsContent = switch (mixin.callable) {
+      AsyncBuiltInCallable(hasContent: var hasContent) ||
+      BuiltInCallable(hasContent: var hasContent) ||
+      UserDefinedCallable(declaration: MixinRule(hasContent: var hasContent)) =>
+        hasContent,
+      AsyncCallable() =>
+        throw UnsupportedError("Unknown callable type $mixin."),
+    };
+    return SassBoolean(acceptsContent);
   })
 ]);
 

lib/src/js.dart

@@ -32,6 +32,7 @@ void main() {
   exports.CalculationInterpolation = calculationInterpolationClass;
   exports.SassColor = colorClass;
   exports.SassFunction = functionClass;
+  exports.SassMixin = mixinClass;
   exports.SassList = listClass;
   exports.SassMap = mapClass;
   exports.SassNumber = numberClass;

lib/src/js/exports.dart

@@ -32,6 +32,7 @@ class Exports {
   external set SassBoolean(JSClass function);
   external set SassColor(JSClass function);
   external set SassFunction(JSClass function);
+  external set SassMixin(JSClass mixin);
   external set SassList(JSClass function);
   external set SassMap(JSClass function);
   external set SassNumber(JSClass function);

lib/src/js/value.dart

@@ -15,6 +15,7 @@ export 'value/color.dart';
 export 'value/function.dart';
 export 'value/list.dart';
 export 'value/map.dart';
+export 'value/mixin.dart';
 export 'value/number.dart';
 export 'value/string.dart';
 
@@ -42,6 +43,7 @@ final JSClass valueClass = () {
     'assertColor': (Value self, [String? name]) => self.assertColor(name),
     'assertFunction': (Value self, [String? name]) => self.assertFunction(name),
     'assertMap': (Value self, [String? name]) => self.assertMap(name),
+    'assertMixin': (Value self, [String? name]) => self.assertMixin(name),
     'assertNumber': (Value self, [String? name]) => self.assertNumber(name),
     'assertString': (Value self, [String? name]) => self.assertString(name),
     'tryMap': (Value self) => self.tryMap(),

lib/src/js/value/mixin.dart

@@ -0,0 +1,22 @@
+// Copyright 2021 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:node_interop/js.dart';
+
+import '../../callable.dart';
+import '../../value.dart';
+import '../reflection.dart';
+import '../utils.dart';
+
+/// The JavaScript `SassMixin` class.
+final JSClass mixinClass = () {
+  var jsClass = createJSClass('sass.SassMixin', () {
+    jsThrow(JsError(
+        'It is not possible to construct a SassMixin through the JavaScript API'));
+  });
+
+  getJSClass(SassMixin(Callable('f', '', (_) => sassNull)))
+      .injectSuperclass(jsClass);
+  return jsClass;
+}();

lib/src/value.dart

@@ -15,6 +15,7 @@ import 'value/color.dart';
 import 'value/function.dart';
 import 'value/list.dart';
 import 'value/map.dart';
+import 'value/mixin.dart';
 import 'value/number.dart';
 import 'value/string.dart';
 import 'visitor/interface/value.dart';
@@ -27,6 +28,7 @@ export 'value/color.dart';
 export 'value/function.dart';
 export 'value/list.dart';
 export 'value/map.dart';
+export 'value/mixin.dart';
 export 'value/null.dart';
 export 'value/number.dart' hide conversionFactor;
 export 'value/string.dart';
@@ -177,6 +179,13 @@ abstract class Value {
   SassFunction assertFunction([String? name]) =>
       throw SassScriptException("$this is not a function reference.", name);
 
+  /// Throws a [SassScriptException] if [this] isn't a mixin reference.
+  ///
+  /// If this came from a mixin argument, [name] is the argument name
+  /// (without the `$`). It's used for error reporting.
+  SassMixin assertMixin([String? name]) =>
+      throw SassScriptException("$this is not a mixin reference.", name);
+
   /// Throws a [SassScriptException] if [this] isn't a map.
   ///
   /// If this came from a function argument, [name] is the argument name

lib/src/value/mixin.dart

@@ -0,0 +1,38 @@
+// Copyright 2016 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:meta/meta.dart';
+
+import '../callable.dart';
+import '../visitor/interface/value.dart';
+import '../value.dart';
+
+/// A SassScript mixin reference.
+///
+/// A mixin reference captures a mixin from the local environment so that
+/// it may be passed between modules.
+///
+/// {@category Value}
+@sealed
+class SassMixin extends Value {
+  /// The callable that this mixin invokes.
+  ///
+  /// Note that this is typed as an [AsyncCallable] so that it will work with
+  /// both synchronous and asynchronous evaluate visitors, but in practice the
+  /// synchronous evaluate visitor will crash if this isn't a [Callable].
+  final AsyncCallable callable;
+
+  SassMixin(this.callable);
+
+  /// @nodoc
+  @internal
+  T accept<T>(ValueVisitor<T> visitor) => visitor.visitMixin(this);
+
+  SassMixin assertMixin([String? name]) => this;
+
+  bool operator ==(Object other) =>
+      other is SassMixin && callable == other.callable;
+
+  int get hashCode => callable.hashCode;
+}

lib/src/visitor/async_evaluate.dart

@@ -417,6 +417,19 @@ final class _EvaluateVisitor
         });
       }, url: "sass:meta"),
 
+      BuiltInCallable.function("module-mixins", r"$module", (arguments) {
+        var namespace = arguments[0].assertString("module");
+        var module = _environment.modules[namespace.text];
+        if (module == null) {
+          throw 'There is no module with namespace "${namespace.text}".';
+        }
+
+        return SassMap({
+          for (var (name, value) in module.mixins.pairs)
+            SassString(name): SassMixin(value)
+        });
+      }, url: "sass:meta"),
+
       BuiltInCallable.function(
           "get-function", r"$name, $css: false, $module: null", (arguments) {
         var name = arguments[0].assertString("name");
@@ -439,6 +452,20 @@ final class _EvaluateVisitor
         return SassFunction(callable);
       }, url: "sass:meta"),
 
+      BuiltInCallable.function("get-mixin", r"$name, $module: null",
+          (arguments) {
+        var name = arguments[0].assertString("name");
+        var module = arguments[1].realNull?.assertString("module");
+
+        var callable = _addExceptionSpan(
+            _callableNode!,
+            () => _environment.getMixin(name.text.replaceAll("_", "-"),
+                namespace: module?.text));
+        if (callable == null) throw "Mixin not found: $name";
+
+        return SassMixin(callable);
+      }, url: "sass:meta"),
+
       AsyncBuiltInCallable.function("call", r"$function, $args...",
           (arguments) async {
         var function = arguments[0];
@@ -512,7 +539,70 @@ final class _EvaluateVisitor
             configuration: configuration,
             namesInErrors: true);
         _assertConfigurationIsEmpty(configuration, nameInError: true);
-      }, url: "sass:meta")
+      }, url: "sass:meta"),
+      BuiltInCallable.mixin("apply", r"$mixin, $args...", (arguments) async {
+        var mixin = arguments[0];
+        var args = arguments[1] as SassArgumentList;
+
+        var callableNode = _callableNode!;
+        var invocation = ArgumentInvocation([], {}, callableNode.span,
+            rest: ValueExpression(args, callableNode.span),
+            keywordRest: args.keywords.isEmpty
+                ? null
+                : ValueExpression(
+                    SassMap({
+                      for (var (name, value) in args.keywords.pairs)
+                        SassString(name, quotes: false): value
+                    }),
+                    callableNode.span));
+
+        var callable = mixin.assertMixin("mixin").callable;
+        // ignore: unnecessary_type_check
+        if (callable is AsyncCallable) {
+          switch (callable) {
+            case BuiltInCallable() when _environment.content != null:
+              throw _exception("Mixin doesn't accept a content block.");
+
+            case BuiltInCallable():
+              await _runBuiltInCallable(invocation, callable, callableNode);
+
+            case UserDefinedCallable<AsyncEnvironment>(
+                  declaration: MixinRule(hasContent: false)
+                )
+                when _environment.content != null:
+              throw MultiSpanSassRuntimeException(
+                  "Mixin doesn't accept a content block.",
+                  callableNode.span,
+                  "invocation",
+                  {callable.declaration.arguments.spanWithName: "declaration"},
+                  _stackTrace(callableNode.span));
+
+            case UserDefinedCallable<AsyncEnvironment>():
+              var contentCallable = _environment.content.andThen((content) =>
+                  UserDefinedCallable(
+                      content as CallableDeclaration, _environment.closure(),
+                      inDependency: _inDependency));
+              _runUserDefinedCallable(invocation, callable, callableNode,
+                  () async {
+                _environment.withContent(contentCallable, () async {
+                  _environment.asMixin(() async {
+                    for (var statement in callable.declaration.children) {
+                      await _addErrorSpan(
+                          callableNode, () => statement.accept(this));
+                    }
+                  });
+                });
+              });
+
+            case _:
+              throw UnsupportedError("Unknown callable type $mixin.");
+          }
+        } else {
+          throw SassScriptException(
+              "The mixin ${callable.name} is asynchronous.\n"
+              "This is probably caused by a bug in a Sass plugin.");
+        }
+      }, url: "sass:meta", hasContent: true),
     ];
 
     var metaModule = BuiltInModule("meta",