[css-values-5] ident() is now an arbitrary-substitution function. #14213

Author: tabatkins

css-values-5/Overview.bs

@@ -2344,26 +2344,34 @@ Constructing <<custom-ident>> values: the ''ident()'' function</h3>
 <wpt>
 ident-function-computed.html
 ident-function-parsing.html
+ident-function-substitution.html
 </wpt>
 
 	<!-- https://github.com/w3c/csswg-drafts/issues/9141 -->
 
-	The <dfn>ident()</dfn> function represents an <<ident>>,
-	and can be used to manually construct <<custom-ident>> values from several parts.
+	The <dfn>ident()</dfn> function represents an arbitrary <<ident>>,
+	built from one or more separate idents, strings, and integers.
+	It is an [=arbitrary substitution function=].
 
 	<pre class=prod>
 	<<ident()>> = ident( <<ident-arg>>+ )
 	<dfn><<ident-arg>></dfn> = <<string>> | <<integer>> | <<ident>>
 	</pre>
 
-	The ''ident()'' function can be used as a value for any property or function argument
-	that accepts a <<custom-ident>>.
+	The ''ident()'' function's [=argument grammar=] is:
+
+	<pre class=prod>
+		<dfn><<ident-args>></dfn> = ident( <<declaration-value>> )
+	</pre>
+
+	''ident()'' can be used anywhere that an [=identifier=] is expected,
+	but it's most useful to construct <<custom-ident>> or <<dashed-ident>> values.
 
 	<div class=example>
 		In the following example,
-		each matched element gets a unique <<'view-timeline-name'>>
-		in the format of <code>"vtl-<em>number</em>"</code>.
-		The <code><em>number</em></code> is generated using ''sibling-index()''.
+		each matched element gets a unique 'view-timeline-name'
+		by combining a shared prefix
+		with ''sibling-index()'' to differentiate each element:
 
 		```css
 		.item {
@@ -2373,12 +2381,13 @@ ident-function-parsing.html
 		```
 	</div>
 
-	While in many cases ''attr()'' with the <<attr-type>> set to <css>type(<<custom-ident>>)</css> will do,
-	''ident()'' can be used to construct a <<custom-ident>> using values that come from other elements.
-
 	<div class=example>
-		In the following example, the  ''ident()'' function uses a custom property
-		which is defined on a parent.
+		While in many cases ''attr()'' with the <<attr-type>> set to <<custom-ident>> will do,
+		''ident()'' can be used to construct a <<custom-ident>> using values that come from other elements.
+		In the following example, 
+		the  ''ident()'' function combines
+		a [=custom property=] defined on a parent
+		with an ''attr()'' value coming from the element itself:
 
 		```css
 		.card[id] {
@@ -2397,17 +2406,44 @@ ident-function-parsing.html
 		```
 	</div>
 
-	To generate a <<dashed-ident>>, put <code>"--"</code> as the first argument.
-
 	<div class=example>
+		To generate a <<dashed-ident>>,
+		simply use a ''--'' ident as the first segment:
 
 		```css
 		.element {
-			anchor-name: ident("--" attr(id));
+			anchor-name: ident(-- attr(id));
 		}
 		```
 	</div>
 
+	<div algorithm>
+		To <dfn export>[=replace an arbitrary substitution function|replace an ident() function=]</dfn>,
+		given a list of |arguments|:
+
+		1. Let |arg| be the first item of |arguments|.
+
+			Note: ''ident()'' only takes a single argument.
+
+		2. [=Substitute arbitrary substitution functions=] in |arg|,
+			then [=CSS/parse=] it as <css><<ident-arg>>+</css>.
+			If that returns failure,
+			return the [=guaranteed-invalid value=].
+			Otherwise, let |pieces| be the result.
+
+		3. Replace each item in |pieces| with its [=computed value=].
+			If any item does not,
+			at this point,
+			become a [=string=], [=integer=], or [=ident=],
+			return the [=guaranteed-invalid value=].
+
+			Note: For example, if the value is a function that can't resolve at [=computed value=] time.
+
+		4. Serialize each item in |pieces|,
+			then [=string/concatenate=] the list.
+			Return an [=ident=] whose value is the result.
+	</div>
+
 <!-- Big Text: random
 
 ████▌   ███▌  █    █▌ ████▌   ███▌  █     █
@@ -5292,6 +5328,7 @@ typed-arithmetic-mixed-units-crash.html
 typed_arithmetic.html
 typed_arithmetic_cycle.html
 update-subpixel-rem-unit.html
+using-font-relative-units-in-font-properties.html
 various-values-important.html
 vh-calc-support-pct.html
 vh-calc-support.html