[scroll-animations-1] Use options dictionary for getCurrentTime() #8201

Author: fantasai

scroll-animations-1/Overview.bs

@@ -1332,42 +1332,58 @@ spec: cssom-view-1; type: dfn;
 	by the {{AnimationTimeline/getCurrentTime()}} method:
 
 	<pre class="idl">
+		dictionary AnimationTimeOptions {
+		  DOMString? range;
+		};
+
 		[Exposed=Window]
 		partial interface AnimationTimeline {
-		  CSSNumericValue? getCurrentTime(optional CSSOMString rangeName);
+		  CSSNumericValue? getCurrentTime(optional AnimationTimeOptions options = {});
 		};
 	</pre>
 
-	<div algorithm="AnimationTimeline.getCurrentTime()">
-		The <code><dfn method for=AnimationTimeline>getCurrentTime(optional |rangeName|)</dfn></code> [=method steps=] are:
-
-		1. If [=this=] is an [=inactive timeline=],
-			return null.
-
-		1. If |rangeName| is provided:
-
-			1. If |rangeName| is a valid [=named timeline range=] on [=this=],
-				let |progress| be the current progress through that range,
-				expressed as a percentage value.
-
-				Create a [=new unit value=] from (|progress|, "percent")
-				and return it.
+	<div class='methods'>
 
-				If the start and end points of the [=named timeline range=] coincide,
-				return negative infinity for time values before it,
-				positive infinity for time values after it,
-				and zero for time values coinciding with that point.
-
-			2. Otherwise, return null.
-
-		2. Let |current time|
-			be the value of [=this's=] {{AnimationTimeline/currentTime}} internal slot.
+		<dt><dfn method for=AnimationTimeline lt='getCurrentTime()'>CSSNumericValue? getCurrentTime(optional AnimationCurrentTimeOptions = {})</dfn>
+		<dd>
+			Returns a representation of the [=timeline/current time=]
+			as follows:
+
+			<dl class="switch">
+				<dt>If {{AnimationTimeOptions/range}} is not provided:
+				<dd>
+					Returns the value of {{AnimationTimeline/currentTime}} on [=this=],
+					but representing millisecond values
+					as a new {{CSSUnitValue}} in ''ms'' units
+					rather than as a double.
+
+				<dt>If {{AnimationTimeOptions/range}} is provided
+					and is a valid [=named timeline range=] on [=this=]:
+				<dd>
+					Let |progress| be the current progress through that range,
+					expressed as a percentage value.
+
+					Create a [=new unit value=] from (|progress|, "percent")
+					and return it.
+
+					If the start and end points of the [=named timeline range=] coincide,
+					return negative infinity for time values before it,
+					positive infinity for time values after it,
+					and zero for time values coinciding with that point.
+
+				<dt>
+					If {{AnimationTimeOptions/range}} is provided
+					but is not a valid [=named timeline range=] on [=this=]:
+				<dd>
+					Returns null.
+			</dl>
+	</div>
 
-			If [=this=] is a {{ScrollTimeline}},
-			create a [=new unit value=] from (|current time|, "percent")
-			and return it.
+	ISSUE(8201): This method is related to {{AnimationTimeline/currentTime}}
+	but not quite the same; should it have a different name?
 
-			Otherwise,
-			create a [=new unit value=] from (|current time|, "ms")
-			and return it.
-	</div>
+	ISSUE: This method returns percentages relative to a ScrollTimeline’s range
+	when a range name is provided.
+	But for time-based timelines, if a range name is provided,
+	should it return percentage progress through that range,
+	or time progress through that range?