[css-mixins-1] Define the @contents rule for passing a style block to a mixin.

Author: tabatkins

css-mixins-1/Overview.bs

@@ -882,12 +882,17 @@ and a [=mixin body=].
 save that it lacks a [=custom function/return type=].)
 
 <pre class="prod def">
-	<<@mixin>> = @mixin <<function-token>> <<function-parameter>>#? )
+	<<@mixin>> = @mixin <<function-token>> <<function-parameter>>#? , @contents? )
 	{
 		<<declaration-rule-list>>
 	}
 </pre>
 
+Differing from the ''@function'' rule,
+the final item in the parameters list
+can be the <<at-keyword-token>> ''@contents'',
+indicating that this [=mixin=] accepts a ''@contents'' block.
+
 If a [=default value=] and a [=parameter type=] are both provided,
 then the default value must parse successfully according to that parameter type’s syntax.
 Otherwise, the ''@mixin'' rule is invalid.
@@ -1039,6 +1044,76 @@ aren't visible to anything outside of the [=mixin body=].
 	and the ''.warning'' rule would not be able to use them.
 </div>
 
+<h3 id='contents-rule'>
+The <dfn>@contents</dfn> Rule</h3>
+
+In addition to accepting arguments passed by the <<dashed-function>> in the ''@apply'' rule,
+a [=mixin=] can accept a <dfn>contents block</dfn>.
+This is indicated by the mixin using a final ''@contents'' <<at-keyword-token>> in its parameter list,
+and is passed by giving the ''@apply'' rule invoking the mixin
+a block.
+
+This allows the invoker of the [=mixin=] to pass an entire style block,
+which the [=mixin=] can then substitute into itself.
+This is useful, for example,
+if the [=mixin=] handles some common conditions for the author,
+and substitutes the [=contents block=] into a predefined ''@media'' or ''@container'' rule.
+
+The syntax of a ''@contents'' at-rule is:
+
+<pre class="prod def">
+	<<@contents>> = @contents [ { <<declaration-list>> } ]?
+</pre>
+
+That is, it is either an <em>empty</em> statement ended immediately by a semicolon,
+or a block treated as a [=nested declarations rule=].
+The empty statement form behaves identically to passing an empty block.
+
+If the [=mixin=] did not declare a ''@contents'' parameter,
+the ''@contents'' rule is ignored,
+substituting with nothing.
+Otherwise, if the ''@apply'' rule invoking the [=mixin=] passed a [=contents block=],
+the ''@contents'' is replaced with the [=contents block=],
+treating it as a [=nested declarations rule=].
+Otherwise, if the ''@apply'' rule did not pass a [=contents block=],
+the ''@contents'' rule is replaced with its own <<declaration-list>>,
+treated as a [=nested declarations rule=].
+
+Outside of a [=mixin body=],
+the ''@contents'' rule is invalid and ignored.
+
+<div class=example>
+	For example, the following mixins
+	abstracts the cases that the page would consider to be appropriate
+	for a "single column" layout,
+	allowing the rest of the page to handle the case without worrying about the details,
+	so the conditions can be adjusted in the future if necessary:
+
+	<pre highlight=css>
+	@mixin --one-column(@contents) {
+		@media (width <= 800px) {
+			@contents;
+		}
+	}
+	@mixin --two-column(@contents) {
+		@media (width > 800px) {
+			@contents;
+		}
+	}
+	body {
+		@apply --one-column {
+			display: flex;
+			flex-flow: column;
+		}
+		@apply --two-column {
+			display: grid;
+			grid-template-columns: ;
+		}
+	}
+	</pre>
+</div>
+
+
 
 Using Mixins {#using-mixins}
 ============================
@@ -1058,7 +1133,7 @@ in place of the ''@apply'' rule itself.
 Its grammar is:
 
 <pre class="prod">
-<<@apply>> = @apply <<dashed-function>> ;
+<<@apply>> = @apply <<dashed-function>> [ { <<declaration-list>> } ]?;
 </pre>
 
 The ''@apply'' rule is only valid
@@ -1084,6 +1159,13 @@ the ''@apply'' application does nothing.
 (Passing too few arguments is fine;
 the missing arguments take their default values instead.)
 
+If the [=mixin=] declares a ''@contents'' parameter,
+and the ''@apply'' rule has a <<declaration-list>> block,
+that block is passed as its [=contents block=].
+If the [=mixin=] did not declare a ''@contents'' parameter,
+having a <<declaration-list>> block makes the ''@apply'' rule invalid
+(similar to passing too many arguments).
+
 
 <!-- Big Text: @env