Support the top-level parent selector (#2758)

Author: nex3

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## 1.99.0
 
+* Add support for parent selectors (`&`) at the root of the document. These are
+  emitted as-is in the CSS output, where they're interpreted as [the scoping
+  root].
+
+  [the scoping root]: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/Nesting_selector#using_outside_nested_rule
+
 * 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.

lib/src/ast/selector/list.dart

@@ -120,12 +120,18 @@ final class SelectorList extends Selector {
   }) {
     if (parent == null) {
       if (preserveParentSelectors) return this;
-      var parentSelector = accept(const _ParentSelectorVisitor());
-      if (parentSelector == null) return this;
-      throw SassException(
-        'Top-level selectors may not contain the parent selector "&".',
-        parentSelector.span,
-      );
+      if (accept(const _ParentSelectorVisitor())
+          case ParentSelector(
+            suffix: var _?,
+            :var span,
+          )) {
+        throw SassException(
+          'A top-level selector may not contain a parent selector with a '
+          'suffix.',
+          span,
+        );
+      }
+      return this;
     }
 
     return SelectorList(

lib/src/functions/selector.dart

@@ -41,24 +41,19 @@ final module = BuiltInModule(
   ],
 );
 
-final _nest = _function("nest", r"$selectors...", (arguments) {
-  var selectors = arguments[0].asList;
-  if (selectors.isEmpty) {
-    throw SassScriptException(
-      "\$selectors: At least one selector must be passed.",
-    );
-  }
-
-  var first = true;
-  return selectors
-      .map((selector) {
-        var result = selector.assertSelector(allowParent: !first);
-        first = false;
-        return result;
-      })
-      .reduce((parent, child) => child.nestWithin(parent))
-      .asSassList;
-});
+final _nest = _function(
+    "nest",
+    r"$selectors...",
+    (arguments) =>
+        arguments[0]
+            .asList
+            .map((selector) => selector.assertSelector(allowParent: true))
+            .fold<SelectorList?>(
+                null, (parent, child) => child.nestWithin(parent))
+            ?.asSassList ??
+        (throw SassScriptException(
+          "\$selectors: At least one selector must be passed.",
+        )));
 
 final _append = _function("append", r"$selectors...", (arguments) {
   var selectors = arguments[0].asList;