From 02ad75aa8b7382604ff8e8e99d65417f08af574b Mon Sep 17 00:00:00 2001
From: andruud <andruud@gmail.com>
Date: Tue, 14 Jan 2025 23:07:34 +0100
Subject: [PATCH] [css-mixins-1] CSSFunctionDeclarations, not
 CSSNestedDeclarations (#11501)

The CSSNestedDeclarations rule does not quite work, since its style
attribute returns a CSSStyleProperties object.

Co-authored-by: Anders Hartvoll Ruud <andruud@google.com>
---
 css-mixins-1/Overview.bs | 53 +++++++++++++++++++++++++++++++++-------
 1 file changed, 44 insertions(+), 9 deletions(-)

diff --git a/css-mixins-1/Overview.bs b/css-mixins-1/Overview.bs
index 1e2e5f65b12..897c9f9d385 100644
--- a/css-mixins-1/Overview.bs
+++ b/css-mixins-1/Overview.bs
@@ -20,6 +20,7 @@ spec:css-properties-values-api; type:dfn; text:syntax component
 spec:css-syntax-3; type:dfn; text:descriptor;
 spec:css-values-4; type:dfn; text:keyword;
 spec:css-values-4; type:dfn; text:identifier;
+spec:cssom-1; type:dfn; text:specified order;
 </pre>
 
 <!-- Big Text: intro
@@ -547,7 +548,7 @@ interface CSSFunctionRule : CSSGroupingRule { };
 While declarations may be specified directly within a ''@function'' rule,
 they are not represented as such in the CSSOM.
 Instead, consecutive segments of declarations
-appear as if wrapped in {{CSSNestedDeclarations}} rules.
+appear as if wrapped in {{CSSFunctionDeclarations}} rules.
 
 Note: This also applies to the "leading" declarations in the ''@function'' rule,
 	i.e those that do not follow another nested rule.
@@ -568,26 +569,60 @@ Note: This also applies to the "leading" declarations in the ''@function'' rule,
 
 	<pre class='lang-css'>
 	@function --bar() {
-	  /* CSSNestedDeclarations { */
+	  /* CSSFunctionDeclarations { */
 	    --x: 42;
 	    result: var(--y);
 	  /* } */
 	  @media (width > 1000px) {
 	    /* ... */
 	  }
-	  /* CSSNestedDeclarations { */
+	  /* CSSFunctionDeclarations { */
 	    --y: var(--x);
 	  /* } */
 	}
 	</pre>
 </div>
 
-Issue: Should we indeed use {{CSSNestedDeclarations}} for this purpose?
-	The <code>style</code> attribute of the {{CSSNestedDeclarations}} rule
-	should probably not be a regular {{CSSStyleDeclaration}},
-	since only custom properties
-	and the '@function/result' descriptor
-	are relevant.
+
+The {{CSSFunctionDeclarations}} Interface {#the-cssnestrule}
+-----------------------------
+
+The {{CSSFunctionDeclarations}} interface represents a run
+of consecutive [=declarations=] within a ''@function'' rule.
+
+<xmp class=idl>
+[Exposed=Window]
+interface CSSFunctionDescriptors : CSSStyleDeclaration {
+	attribute [LegacyNullToEmptyString] CSSOMString result;
+};
+
+[Exposed=Window]
+interface CSSFunctionDeclarations : CSSRule {
+	[SameObject, PutForwards=cssText] readonly attribute CSSFunctionDescriptors style;
+};
+</xmp>
+
+<div algorithm>
+	The <dfn attribute for=CSSFunctionDeclarations>style</dfn> attribute
+	must return a {{CSSFunctionDescriptors}} object for the rule,
+	with the following properties:
+
+	: [=CSSStyleDeclaration/computed flag=]
+	:: Unset
+	: [=CSSStyleDeclaration/readonly flag=]
+	:: Unset
+	: [=CSSStyleDeclaration/declarations=]
+	:: The declared declarations in the rule, in [=specified order=].
+		<span class=note>This includes any [=local variables=].</span>
+	: [=CSSStyleDeclaration/parent CSS rule=]
+	:: [=this=]
+	: [=CSSStyleDeclaration/owner node=]
+	:: Null
+</div>
+
+The {{CSSFunctionDeclarations}} rule, like {{CSSNestedDeclarations}},
+[=serialize a CSS rule|serializes=] as if its [=CSS declaration block|declaration block=]
+had been [=serialize a CSS declaration block|serialized=] directly.
 
 Privacy Considerations {#privacy}
 ===============================================