Merge pull request #3885 from sass/interleaved-decls

See #3846

accepted/interleaved-declarations.changes.md

@@ -0,0 +1,5 @@
+## Draft 1.1
+
+* Remove the `@nest` rule as it was removed from CSS.
+
+* Produce a deprecation warning for declarations in non-top-level contexts.

accepted/interleaved-declarations.md

@@ -1,6 +1,7 @@
-# Interleaved Declarations: Draft 1
+# Interleaved Declarations: Draft 1.1
 
-*([Issue](https://github.com/sass/sass/issues/3846))*
+*([Issue](https://github.com/sass/sass/issues/3846),
+[Changelog](interleaved-declarations.changes.md))*
 
 ## Table of Contents
 
@@ -11,8 +12,6 @@
   * [Current Keyframe Block](#current-keyframe-block)
 * [Declarations](#declarations)
   * [Semantics](#semantics)
-* [Unknown At-Rules](#unknown-at-rules)
-  * [Semantics](#semantics-1)
 * [Deprecation Process](#deprecation-process)
 
 ## Background
@@ -122,26 +121,13 @@ before "Append `css` to `parent`":
 [current style rule]: #current-style-rule
 [keyframe block]: #current-keyframe-block
 
-## Unknown At-Rules
-
-### Semantics
-
-Add the following to the semantics for executing an unknown at-rule `rule` after
-"If `rule`'s name is 'font-face', or if its unprefixed name is 'keyframes',
-append `css` to the current module's CSS":
-
-* If `rule`'s name is case-insensitively equal to "nest", append `css` to
-  `parent`.
-
 ## Deprecation Process
 
 This proposal's change to the semantics of interleaved declarations is
 backwards-incompatible. Before changing to the new semantics, an implementation
 should have a period of deprecation in which it emits a deprecation warning for
-a declaration whose `parent` is not the last statement in [the current module]'s
-CSS without changing the existing behavior.
-
-[the current module]: ../spec/spec.md#current-module
+a declaration whose `parent` is not the last statement in its parent without
+changing the existing behavior.
 
 > Authors can move interleaved declarations before any nested rules to preserve
 > existing behavior, or nest them in `& { ... }` style rules to anticipate the

js-api-doc/deprecations.d.ts

@@ -6,7 +6,7 @@
  */
 export interface Deprecations {
   // START AUTOGENERATED LIST
-  // Checksum: 22d9bdbe92eb39b3c0d6d64ebe1879a431c0037e
+  // Checksum: 309e4f1f008f08379b824ab6094e13df2e18e187
 
   /**
    * Deprecation for passing a string directly to meta.call().
@@ -113,6 +113,13 @@ export interface Deprecations {
    */
   'css-function-mixin': Deprecation<'css-function-mixin'>;
 
+  /**
+   * Deprecation for declarations after or between nested rules.
+   *
+   * This deprecation became active in Dart Sass 1.77.7.
+   */
+  'mixed-decls': Deprecation<'mixed-decls'>;
+
   /**
    * Deprecation for @import rules.
    *

spec/at-rules/nest.md

@@ -0,0 +1,33 @@
+# `@nest` Rule
+
+Sass has special semantics for the `@nest` rule. Although this rule is primarily
+intended to give the CSSOM a consistent representation for interleaved
+declarations and is never required to be written explicitly, it *is* valid CSS
+and Sass must ensure that its use preserves the existing CSS semantics.
+
+## Syntax
+
+<x><pre>
+**NestRule** ::= '@nest'¹ '{' Statements '}'
+</pre></x>
+
+1: This is case-insensitive.
+
+## Semantics
+
+To execute a `@nest` rule `rule`:
+
+* If there's a [current keyframe block], throw an error.
+
+  [current keyframe block]: ../style-rules.md#current-keyframe-block
+
+* If there's a [current style rule], evaluate each child in `rule`'s
+  `Statement`s.
+
+  [current style rule]: ../style-rules.md#current-style-rule
+
+* Otherwise, [evaluate `rule` as an unknown at-rule] with
+  `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same
+  `Statements`.
+
+  [evaluate `rule` as an unknown at-rule]: ../at-rules/unknown.md

spec/declarations.md

@@ -75,5 +75,16 @@ To execute a declaration `declaration`:
   * Let `css` be a CSS declaration with name `name` and value `value`.
 
   * Append `css` to `parent`.
+  
+  * If `parent` isn't the last statement in its parent:
+
+    * Let `copy` by a copy of `parent` without any children.
+
+    * Append `copy` to `parent`'s parent.
+
+    * Set the [current style rule], [keyframe block], or at-rule (according to
+      `copy`'s type) to `copy`, for the remaining duration of its previous value.
+
+    * Set `parent` to `copy`.
 
 * Evaluate each child in `declaration`'s `Statements` if it exists.

spec/deprecations.yaml

@@ -106,6 +106,12 @@ css-function-mixin:
     status: active
     deprecated: 1.76.0
 
+mixed-decls:
+  description: Declarations after or between nested rules.
+  dart-sass:
+    status: active
+    deprecated: 1.77.7
+
 import:
   description: "@import rules."
   dart-sass:

spec/js-api/deprecations.d.ts.md

@@ -29,7 +29,7 @@
 ### `Deprecations`
 
 <!-- START AUTOGENERATED LIST -->
-<!-- Checksum: 22d9bdbe92eb39b3c0d6d64ebe1879a431c0037e -->
+<!-- Checksum: 309e4f1f008f08379b824ab6094e13df2e18e187 -->
 ```ts
 export interface Deprecations {
   'call-string': Deprecation<'call-string'>;
@@ -47,6 +47,7 @@ export interface Deprecations {
   'abs-percent': Deprecation<'abs-percent'>;
   'fs-importer-cwd': Deprecation<'fs-importer-cwd'>;
   'css-function-mixin': Deprecation<'css-function-mixin'>;
+  'mixed-decls': Deprecation<'mixed-decls'>;
   import: Deprecation<'import'>;
   'user-authored': Deprecation<'user-authored', 'user'>;
 }

spec/style-rules.md

@@ -13,12 +13,15 @@
 
 The *current style rule* is the CSS style rule that was created by the innermost
 [execution of a style rule](#semantics), `@media` rule, `@supports` rule, or
-unknown at-rule.
+unknown at-rule. This may be overridden by the [execution of a declaration].
+
+[execution of a declaration]: declarations.md#semantics
 
 ### Current Keyframe Block
 
 The *current keyframe block* is the CSS keyframe block that was created by the
-innermost [execution of a style rule](#semantics).
+innermost [execution of a style rule](#semantics). This may be overridden by the
+[execution of a declaration].
 
 ## Semantics