[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>

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>.