[css-mixins-1] Use the <syntax> Production for param types (#10496)

* [css-mixins-1] Use the <syntax> Production for param types

* Whitespace (again).

Co-authored-by: Miriam Suzanne <miriam@oddbird.net>

---------

Co-authored-by: Miriam Suzanne <miriam@oddbird.net>

Author: andruud

css-mixins-1/Overview.bs

@@ -15,8 +15,11 @@ Default Highlight: css
 
 <pre class=link-defaults>
 spec:infra; type:dfn; text:list
-spec:css-properties-values-api; type:dfn; text:syntax string
+spec:css-properties-values-api; type:dfn; text:supported syntax component name
+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;
 </pre>
 
 <!-- Big Text: intro
@@ -98,27 +101,46 @@ The ''@function'' rule defines a [=custom function=],
 and its syntax is:
 
 <pre class="prod def" nohighlight>
-@function <<function-name>> [( <<parameter-list>> )]?
-	[using (<<dependency-list>>)]?
-	[returns type(<<string>>)]?
+@function <<function-name>> [ ( <<parameter-list>> ) ]?
+	[ using ( <<dependency-list>> ) ]?
+	[ returns <<type>> ]?
 {
 	<<declaration-rule-list>>
 }
 
 <dfn><<function-name>></dfn> = <<dashed-ident>>
 <dfn><<parameter-list>></dfn> = <<parameter>>#
 <dfn><<dependency-list>></dfn> = <<parameter>>#
-<dfn><<parameter>></dfn> = <<custom-property-name>> type(<<string>>)? [ : <<declaration-value>> ]?
+<dfn><<type>></dfn> = <<syntax-component>> | type( <<syntax>> )
+<dfn><<parameter>></dfn> = <<custom-property-name>> <<type>>? [ : <<declaration-value>> ]?
 </pre>
 
 The name of the resulting [=custom function=] is given by the <<function-name>>,
 the [=function parameters=] are optionally given by <<parameter-list>>,
 the [=function dependencies=] are optionally given by <<dependency-list>>,
-and the [=return type=] is optionally given by the type string following the "returns" keyword.
+and the [=return type=] is optionally given by the <<type>> following the "returns" keyword.
 
-If a [=syntax string=] provided for a [=function parameter=] or [=function dependency=] is unrecognized,
-or the [=syntax string=] provided for the [=return type=] is unrecognized,
-then the ''@function'' rule is invalid.
+<div class='example'>
+	If the <<type>> of a [=function parameter=],
+	[=function dependency=],
+	or [=custom function=] return value
+	can be described by a single <<syntax-component>>,
+	then the <code>type()</code> function may be omitted:
+
+	<pre class='lang-css'>
+	@function --foo(--a &lt;length&gt;) { /* ... */ }
+	@function --foo(--a &lt;color&gt;) { /* ... */ }
+	@function --foo(--a &lt;length&gt;+) { /* ... */ }
+	</pre>
+
+	However,
+	any <<syntax>> that requires a <<combinator>>
+	needs to be wrapped in the <code>type()</code> function:
+
+	<pre class='lang-css'>
+	@function --foo(--a type(&lt;number&gt; | &lt;percentage&gt;)) { /* ... */ }
+	</pre>
+</div>
 
 Issue: Should duplicates be disallowed <em>across</em> parameters/dependencies
 	as well?
@@ -563,3 +585,90 @@ Issue: Should we indeed use {{CSSNestedDeclarations}} for this purpose?
 	since only custom properties
 	and the '@function/result' descriptor
 	are relevant.
+
+<!-- Big Text: appendix
+
+ ███▌  ████▌  ████▌  █████▌ █    █▌ ████▌  ████ █     █
+▐█ ▐█  █▌  █▌ █▌  █▌ █▌     █▌   █▌ █▌  █▌  ▐▌   █   █ 
+█▌  █▌ █▌  █▌ █▌  █▌ █▌     ██▌  █▌ █▌  █▌  ▐▌    █ █  
+█▌  █▌ ████▌  ████▌  ████   █▌▐█ █▌ █▌  █▌  ▐▌     █   
+█████▌ █▌     █▌     █▌     █▌  ██▌ █▌  █▌  ▐▌    █ █  
+█▌  █▌ █▌     █▌     █▌     █▌   █▌ █▌  █▌  ▐▌   █   █ 
+█▌  █▌ █▌     █▌     █████▌ █▌   ▐▌ ████▌  ████ █     █
+-->
+
+Appendix: The <<syntax>> Production {#syntax}
+=============================================
+
+The <<syntax>> production represents a [=syntax definition=],
+which may be used to impose a type
+on [=function parameters=],
+[=function dependencies=],
+or [=custom function=] return values.
+
+<pre class="prod def" nohighlight>
+
+<dfn><<type-name>></dfn> = angle | color | custom-ident | image | integer |
+	length | length-percentage | number |
+	percentage | resolution | string | time |
+	url | transform-function
+<dfn><<combinator>></dfn> = '|'
+<dfn><<multiplier>></dfn> = [ '#' | '+' ]
+<dfn><<syntax-component-name>></dfn> = '<' <<type-name>> '>' | <<custom-ident>>
+<dfn><<syntax-component>></dfn> = <<syntax-component-name>> <<multiplier>>? |
+	'<' transform-list '>'
+<dfn><<syntax>></dfn> = '*' | <<syntax-component>> [ <<combinator>> <<syntax-component>> ]+
+
+</pre>
+
+A <<syntax-component>> consists of either a <<type-name>>,
+which maps to one of the [=supported syntax component names=];
+or a <<custom-ident>>, which represents any [=keyword=].
+Additionally,
+a <<syntax-component>> may contain a [[css-properties-values-api-1#multipliers|multiplier]],
+which indicates a [=list=] of values.
+
+Note: This means that <code>&lt;length&gt;</code>
+	and <code>length</code> are two different types:
+	the former describes a <<length>>,
+	whereas the latter describes a [=keyword=] <code>length</code>.
+
+Multiple <<syntax-component>>s may be [[css-properties-values-api-1#combinator|combined]]
+with a <code>|</code> <<delim-token>>,
+causing the syntax components to be matched
+against a value
+in the specified order.
+
+<div class='example'>
+	<pre class='lang-css'>
+	&lt;percentage&gt; | &lt;number&gt; | auto
+	</pre>
+	The above, when parsed as a <<syntax>>,
+	would accept <<percentage>> values,
+	<<number>> values,
+	as well as the keyword <code>auto</code>.
+</div>
+
+<div class='example'>
+	<pre class='lang-css'>
+	red | &lt;color&gt;
+	</pre>
+	The [=syntax definition=] resulting from the above <<syntax>>,
+	when used as a grammar for [=parse|parsing=],
+	would match an input <code>red</code> as an [=identifier=],
+	but would match an input <code>blue</code> as a <<color>>.
+</div>
+
+The <code>*</code> <<delim-token>> represents the [=universal syntax definition=].
+
+The <code>&lt;transform-list&gt;</code> production
+is a convenience form equivalent to <code>&lt;transform-function&gt;+</code>.
+<span class=note>Note that <code>&lt;transform-list&gt;</code> may not
+	be followed by a <<multiplier>>.</span>
+
+[=Whitespace=] is not allowed
+between the angle bracket <<delim-token>>s (<code>&lt;</code> <code>&gt;</code>)
+and the <<type-name>> they enclose,
+nor is [=whitespace=] allowed to precede a <<multiplier>>.
+
+Note: The [=whitespace=] restrictions also apply to <code>&lt;transform-list&gt;</code>.