From 79799ca5757682790a31f80b698803d420d5e73e Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 18 Jun 2024 17:08:12 -0700 Subject: [PATCH 1/3] [Interleaved Declarations] Mark as accepted See #3846 --- {proposal => accepted}/interleaved-declarations.md | 0 js-api-doc/deprecations.d.ts | 9 ++++++++- spec/at-rules/unknown.md | 3 +++ spec/declarations.md | 11 +++++++++++ spec/deprecations.yaml | 6 ++++++ spec/js-api/deprecations.d.ts.md | 3 ++- spec/style-rules.md | 7 +++++-- 7 files changed, 35 insertions(+), 4 deletions(-) rename {proposal => accepted}/interleaved-declarations.md (100%) diff --git a/proposal/interleaved-declarations.md b/accepted/interleaved-declarations.md similarity index 100% rename from proposal/interleaved-declarations.md rename to accepted/interleaved-declarations.md diff --git a/js-api-doc/deprecations.d.ts b/js-api-doc/deprecations.d.ts index 390f361d..c2512c62 100644 --- a/js-api-doc/deprecations.d.ts +++ b/js-api-doc/deprecations.d.ts @@ -6,7 +6,7 @@ */ export interface Deprecations { // START AUTOGENERATED LIST - // Checksum: 22d9bdbe92eb39b3c0d6d64ebe1879a431c0037e + // Checksum: 6e5aeefc72f4e9b4ffa0672feea75a5ad09b0282 /** * 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. + */ + 'interleaved-decls': Deprecation<'interleaved-decls'>; + /** * Deprecation for @import rules. * diff --git a/spec/at-rules/unknown.md b/spec/at-rules/unknown.md index eff2d183..44cc4e3a 100644 --- a/spec/at-rules/unknown.md +++ b/spec/at-rules/unknown.md @@ -43,6 +43,9 @@ To execute an unknown at-rule `rule`: * If `rule`'s name is "font-face", or if its [unprefixed] name is "keyframes", append `css` to [the current module]'s CSS. + * Otherwise, if `rule`'s name is case-insensitively equal to "nest", append + `css` to `parent`. + * Otherwise: * Append `css` to `parent`'s parent. diff --git a/spec/declarations.md b/spec/declarations.md index 17e66bc3..23220b45 100644 --- a/spec/declarations.md +++ b/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. diff --git a/spec/deprecations.yaml b/spec/deprecations.yaml index 38be698f..ab74a639 100644 --- a/spec/deprecations.yaml +++ b/spec/deprecations.yaml @@ -106,6 +106,12 @@ css-function-mixin: status: active deprecated: 1.76.0 +interleaved-decls: + description: Declarations after or between nested rules. + dart-sass: + status: active + deprecated: 1.77.7 + import: description: "@import rules." dart-sass: diff --git a/spec/js-api/deprecations.d.ts.md b/spec/js-api/deprecations.d.ts.md index 27c130f1..e27368fa 100644 --- a/spec/js-api/deprecations.d.ts.md +++ b/spec/js-api/deprecations.d.ts.md @@ -29,7 +29,7 @@ ### `Deprecations` - + ```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'>; + 'interleaved-decls': Deprecation<'interleaved-decls'>; import: Deprecation<'import'>; 'user-authored': Deprecation<'user-authored', 'user'>; } diff --git a/spec/style-rules.md b/spec/style-rules.md index 817e8553..4c9f8f32 100644 --- a/spec/style-rules.md +++ b/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 From 4411ebae22e9a3fad99770fd9de7774dcf139a21 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Tue, 18 Jun 2024 19:44:39 -0700 Subject: [PATCH 2/3] Update based on implementation experience --- accepted/interleaved-declarations.changes.md | 5 ++ accepted/interleaved-declarations.md | 71 ++++++++++++++++---- js-api-doc/deprecations.d.ts | 4 +- spec/at-rules/nest.md | 33 +++++++++ spec/at-rules/unknown.md | 3 - spec/deprecations.yaml | 2 +- spec/js-api/deprecations.d.ts.md | 4 +- 7 files changed, 102 insertions(+), 20 deletions(-) create mode 100644 accepted/interleaved-declarations.changes.md create mode 100644 spec/at-rules/nest.md diff --git a/accepted/interleaved-declarations.changes.md b/accepted/interleaved-declarations.changes.md new file mode 100644 index 00000000..eaea42a4 --- /dev/null +++ b/accepted/interleaved-declarations.changes.md @@ -0,0 +1,5 @@ +## Draft 1.1 + +* Make sure the `@nest` rule follows the new CSS semantics. + +* Produce a deprecation warning for declarations in non-top-level contexts. diff --git a/accepted/interleaved-declarations.md b/accepted/interleaved-declarations.md index 469f9809..06413ba4 100644 --- a/accepted/interleaved-declarations.md +++ b/accepted/interleaved-declarations.md @@ -1,6 +1,7 @@ # Interleaved Declarations: Draft 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,9 +12,11 @@ * [Current Keyframe Block](#current-keyframe-block) * [Declarations](#declarations) * [Semantics](#semantics) -* [Unknown At-Rules](#unknown-at-rules) +* [`@nest` Rule](#nest-rule) + * [Syntax](#syntax) * [Semantics](#semantics-1) * [Deprecation Process](#deprecation-process) + * [`@nest` Rule](#nest-rule-1) ## Background @@ -122,27 +125,71 @@ before "Append `css` to `parent`": [current style rule]: #current-style-rule [keyframe block]: #current-keyframe-block -## Unknown At-Rules +## `@nest` Rule + +Add 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. + +> This is also provides an explicit way for Sass authors to write styles that +> are consistent with CSS semantics during the deprecation period for +> interleaved declarations. + +### Syntax + +
+**NestRule** ::= '@nest'¹ '{' Statements '}'
+
 + +1: This is case-insensitive. ### 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": +To execute a `@nest` rule `rule`: -* If `rule`'s name is case-insensitively equal to "nest", append `css` to - `parent`. +* If there's a [current keyframe block], throw an error. + + [current keyframe block]: #current-keyframe-block + +* If there's a [current style rule], evaluate each child in `rule`'s + `Statement`s. + +* Otherwise, [evaluate `rule` as an unknown at-rule] with + `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same + `Statements`. + + [evaluate `rule` as an unknown at-rule]: ../spec/at-rules/unknown.md ## 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 > new behavior. + +### `@nest` Rule + +During the deprecation period, use the `@nest` syntax specified above but the +following semantics: + +* If there's a [current keyframe block], throw an error. + +* If there's a [current style rule] `style-rule`: + + * If `style-rule`'s stylesheet was [parsed as CSS], evaluate each child in + `rule`'s `Statement`s. + + * Otherwise, [evaluate `rule` as a style rule with `SelectorList` "&" and the + same `Statements`. + +* Otherwise, [evaluate `rule` as an unknown at-rule] with + `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same + `Statements`. + +[parsed as CSS]: ../spec/syntax.md#parsing-text-as-css diff --git a/js-api-doc/deprecations.d.ts b/js-api-doc/deprecations.d.ts index c2512c62..3c7fe551 100644 --- a/js-api-doc/deprecations.d.ts +++ b/js-api-doc/deprecations.d.ts @@ -6,7 +6,7 @@ */ export interface Deprecations { // START AUTOGENERATED LIST - // Checksum: 6e5aeefc72f4e9b4ffa0672feea75a5ad09b0282 + // Checksum: 309e4f1f008f08379b824ab6094e13df2e18e187 /** * Deprecation for passing a string directly to meta.call(). @@ -118,7 +118,7 @@ export interface Deprecations { * * This deprecation became active in Dart Sass 1.77.7. */ - 'interleaved-decls': Deprecation<'interleaved-decls'>; + 'mixed-decls': Deprecation<'mixed-decls'>; /** * Deprecation for @import rules. diff --git a/spec/at-rules/nest.md b/spec/at-rules/nest.md new file mode 100644 index 00000000..b6aa1721 --- /dev/null +++ b/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 + +
+**NestRule** ::= '@nest'¹ '{' Statements '}'
+
 + +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 diff --git a/spec/at-rules/unknown.md b/spec/at-rules/unknown.md index 44cc4e3a..eff2d183 100644 --- a/spec/at-rules/unknown.md +++ b/spec/at-rules/unknown.md @@ -43,9 +43,6 @@ To execute an unknown at-rule `rule`: * If `rule`'s name is "font-face", or if its [unprefixed] name is "keyframes", append `css` to [the current module]'s CSS. - * Otherwise, if `rule`'s name is case-insensitively equal to "nest", append - `css` to `parent`. - * Otherwise: * Append `css` to `parent`'s parent. diff --git a/spec/deprecations.yaml b/spec/deprecations.yaml index ab74a639..f07c7391 100644 --- a/spec/deprecations.yaml +++ b/spec/deprecations.yaml @@ -106,7 +106,7 @@ css-function-mixin: status: active deprecated: 1.76.0 -interleaved-decls: +mixed-decls: description: Declarations after or between nested rules. dart-sass: status: active diff --git a/spec/js-api/deprecations.d.ts.md b/spec/js-api/deprecations.d.ts.md index e27368fa..4ab9729c 100644 --- a/spec/js-api/deprecations.d.ts.md +++ b/spec/js-api/deprecations.d.ts.md @@ -29,7 +29,7 @@ ### `Deprecations` - + ```ts export interface Deprecations { 'call-string': Deprecation<'call-string'>; @@ -47,7 +47,7 @@ export interface Deprecations { 'abs-percent': Deprecation<'abs-percent'>; 'fs-importer-cwd': Deprecation<'fs-importer-cwd'>; 'css-function-mixin': Deprecation<'css-function-mixin'>; - 'interleaved-decls': Deprecation<'interleaved-decls'>; + 'mixed-decls': Deprecation<'mixed-decls'>; import: Deprecation<'import'>; 'user-authored': Deprecation<'user-authored', 'user'>; } From 674e6447aab33ea12e7106e80e7a0b266401c2b3 Mon Sep 17 00:00:00 2001 From: Natalie Weizenbaum Date: Wed, 3 Jul 2024 17:28:18 -0700 Subject: [PATCH 3/3] [Interleaved Decls] Remove `@nest` See w3c/csswg-drafts#10234 --- accepted/interleaved-declarations.changes.md | 2 +- accepted/interleaved-declarations.md | 63 +------------------- 2 files changed, 2 insertions(+), 63 deletions(-) diff --git a/accepted/interleaved-declarations.changes.md b/accepted/interleaved-declarations.changes.md index eaea42a4..7fe4b764 100644 --- a/accepted/interleaved-declarations.changes.md +++ b/accepted/interleaved-declarations.changes.md @@ -1,5 +1,5 @@ ## Draft 1.1 -* Make sure the `@nest` rule follows the new CSS semantics. +* Remove the `@nest` rule as it was removed from CSS. * Produce a deprecation warning for declarations in non-top-level contexts. diff --git a/accepted/interleaved-declarations.md b/accepted/interleaved-declarations.md index 06413ba4..5c5d502f 100644 --- a/accepted/interleaved-declarations.md +++ b/accepted/interleaved-declarations.md @@ -1,4 +1,4 @@ -# Interleaved Declarations: Draft 1 +# Interleaved Declarations: Draft 1.1 *([Issue](https://github.com/sass/sass/issues/3846), [Changelog](interleaved-declarations.changes.md))* @@ -12,11 +12,7 @@ * [Current Keyframe Block](#current-keyframe-block) * [Declarations](#declarations) * [Semantics](#semantics) -* [`@nest` Rule](#nest-rule) - * [Syntax](#syntax) - * [Semantics](#semantics-1) * [Deprecation Process](#deprecation-process) - * [`@nest` Rule](#nest-rule-1) ## Background @@ -125,42 +121,6 @@ before "Append `css` to `parent`": [current style rule]: #current-style-rule [keyframe block]: #current-keyframe-block -## `@nest` Rule - -Add 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. - -> This is also provides an explicit way for Sass authors to write styles that -> are consistent with CSS semantics during the deprecation period for -> interleaved declarations. - -### Syntax - -
-**NestRule** ::= '@nest'¹ '{' Statements '}'
-
 - -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]: #current-keyframe-block - -* If there's a [current style rule], evaluate each child in `rule`'s - `Statement`s. - -* Otherwise, [evaluate `rule` as an unknown at-rule] with - `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same - `Statements`. - - [evaluate `rule` as an unknown at-rule]: ../spec/at-rules/unknown.md - ## Deprecation Process This proposal's change to the semantics of interleaved declarations is @@ -172,24 +132,3 @@ 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 > new behavior. - -### `@nest` Rule - -During the deprecation period, use the `@nest` syntax specified above but the -following semantics: - -* If there's a [current keyframe block], throw an error. - -* If there's a [current style rule] `style-rule`: - - * If `style-rule`'s stylesheet was [parsed as CSS], evaluate each child in - `rule`'s `Statement`s. - - * Otherwise, [evaluate `rule` as a style rule with `SelectorList` "&" and the - same `Statements`. - -* Otherwise, [evaluate `rule` as an unknown at-rule] with - `InterpolatedIdentifier` "nest", no `InterpolatedValue`, and the same - `Statements`. - -[parsed as CSS]: ../spec/syntax.md#parsing-text-as-css