[css-properties-values-api] Big rewrite of apply hook section.

Author: shans

css-properties-values-api/Overview.bs

@@ -15,6 +15,10 @@ Editor: Greg Whitworth, gwhit@microsoft.com
 Ignored Terms: boolean, Animatable, Map, Context, isolated worker, SyntaxError,
 Ignored Terms: InvalidModificationError, NotFoundError, StylePropertyMapReadOnly,
 Ignored Terms: processor global scope
+Ignored Terms: Worklet, throw, NotSupportedError, isconstructor, get, iscallable,
+Ignored Terms: construct, name map of inputs, invoke a method on a class inside a worklet
+Ignored Terms: create a worklet global scope, lookup a class instance on a worklet global scope
+Ignored Vars: arguments, methodPropertyKey, inputStyleMap, workletGlobalScope
 Repository: w3c/css-houdini-drafts
 At Risk: the apply hook (<a section href="#the-apply-hook"></a>)
 </pre>
@@ -221,20 +225,29 @@ interface ElementProxy {
   readonly attribute DOMString? pseudo;
 };
 
-callback ApplyCallback = void (ElementProxy element);
-
 dictionary ApplyDescriptor {
-  ApplyCallback applyHook;
   sequence&lt;DOMString&gt; inputProperties;
   sequence&lt;DOMString&gt; outputProperties;
 };
 
-partial interface Context {
-  long registerApplyHook(ApplyDescriptor apply);
-  void unregisterApplyHook(long hookID);
+callback VoidFunction = void ();
+
+interface StyleWorklet : Worklet {
+  void registerApplyHook(DOMString name, VoidFunction applyCtor, ApplyDescriptor config);
+  void unregisterApplyHook(DOMString name);
 };
 </pre>
 
+<div class='note'>
+The applyCtor is a JavaScript class with the following interface:
+
+<pre class='idl'>
+callback interface ApplyClass {
+  void apply(ElementProxy element);
+};
+</pre>
+</div>
+
 The {{ElementProxy}} interface {#the-elementproxy-interface}
 ------------------------------------------------------------
 
@@ -272,30 +285,112 @@ Issue(2): Should this be available only if explicitly requested in inputProperti
 ::  This value defines the properties for which the apply function can modify the used
     value.
 
+Apply classes {#apply-class-objects}
+------------------------------------
+
+<dfn>Apply classes</dfn> provide apply hook behavior. Each <a>apply class</a>
+must provide an apply function that will be invoked when apply hooks are
+being processed.
+
+The {{StyleWorklet}} interface {#the-styleworklet-interface}
+------------------------------------------------------------
+
+<dfn interface>StyleWorklet</dfn> objects provide the context within which apply hooks
+are invoked. Each {{StyleWorklet}} contains a <dfn>name map of apply hooks</dfn>,
+a <dfn>name map of inputs</dfn>, a <dfn>name map of outputs</dfn>,
+and a <dfn>list of affected output properties</dfn>, all of which are
+initially empty.
+
 The {{registerApplyHook()}} function {#the-registerapplyhook-function}
 ----------------------------------------------------------------------
 
-If a {{registerApplyHook()}} call is made with a list of outputProperties that contains
-properties that have already been registered for output, then an exception is thrown and
-the call fails.
+The <dfn method for=StyleWorklet>registerApplyHook(DOMString name, VoidFunction applyCtor, ApplyDescriptor config)</dfn>
+ function registers a new apply hook for processing computed style.
+
+When {{registerApplyHook(name, applyCtor, config)}} is called, the user agent must run the following steps:
+
+1.  If |name| is not a valid <<ident>>, <a>throw</a> a {{NotSupportedError}} and abort
+    these steps.
+
+1.  If |name| is a key in the <a>name map of apply hooks</a>, <a>throw</a> a
+    {{NotSupportedError}} and abort these steps.
+
+1.  Let <var>outputProperties</var> be the value of |config|'s
+    {{ApplyDescriptor/outputProperties}}.
+
+1.  If the |outputProperties| contains a property
+    that is in the <a>list of affected output properties</a>, <a>throw</a> a
+    {{NotSupportedError}} and abort these steps.
 
-Issue(49): This is too inflexible. There’s a strong use case around writing to the
-same native property for different elements. Maybe throw exception to
-window.onError in this case?
+    Issue(49): This is too inflexible. There’s a strong use case around writing to the
+    same native property for different elements. Maybe throw exception to
+    window.onError in this case?
+
+1.  If the result of <a>IsConstructor</a>(argument=|applyCtor|) is false,
+    <a>throw</a> a {{NotSupportedError}} and abort these steps.
+
+1.  Let <var>prototype</var> be the result of <a>Get</a>(O=|applyCtor|, P="prototype").
+
+1.  If the result of <a>IsCallable</a>(argument=<a>Get</a>(O=|prototype|, P="apply"))
+    is false, <a>throw</a> a {{NotSupportedError}} and abort these steps.
+
+1.  Let <var>applyInstance</var> be the result of <a>Construct</a>(|applyCtor|).
+
+1.  Add the key-value pair (|name| - |applyInstance|) to the
+    <a>name map of apply hooks</a> of the {{StyleWorklet}}.
+
+1.  Add each property in |outputProperties| to
+    the <a>list of affected output properties</a> of the {{StyleWorklet}}.
+
+1.  Add the key-value pair (|name| - |outputProperties|) to the
+    <a>name map of outputs</a> of the {{StyleWorklet}}.
+
+1.  Let <var>inputProperties</var> be the value of |config|'s
+    {{ApplyDescriptor/inputProperties}}.
+
+1.  Add the key-value pair (|name| - |inputProperties|) to the
+    <a>name map of inputs</a> of the {{StyleWorklet}}.
+
+Issue: This is one instance per apply hook. Do we want one instance per invocation?
 
 Invoking apply hooks {#invoking-apply-hooks}
 --------------------------------------------
 
-Each time style is recomputed for an Element, each registered {{ApplyDescriptor/applyHook}}
+Each time style is recomputed for an Element, each registered ApplyDescriptor/applyHook
 for which any of the matching {{ApplyDescriptor/inputProperties}} changes as a result of
 that recomputation is invoked. This invocation happens after any transitions or animations
-registered on the Element have finished applying.
+registered on the Element have finished applying, in the context of a {{StyleWorklet}}.
 
 Note: apply hooks are called after transitions/animations so that custom properties
       can be transitioned and still have their effect apply correctly.
 
-This invocation takes place in an <a>isolated worker</a>.
+This invocation takes place by following these steps for each key <var>name</var>
+in the <a>name map of apply hooks</a>:
+
+1.  Let <var>inputs</var> be the result of looking up <var>name</var> on the
+    {{StyleWorklet}}'s <a>name map of inputs</a>.
+
+1.  Let <var>inputStyleMap</var> be a new {{StylePropertyMapReadOnly}} populated
+    with only the <a>computed value</a>s for properties listed in |inputs|.
+
+1.  Let <var>proxy</var> be a new {{ElementProxy}}.
+
+    Issue: Need to fill out the ElementProxy.
+
+1.  <a>invoke a method on a class inside a Worklet</a> given "apply" as the
+    <var>methodPropertyKey</var> and [|proxy|] as the <var>arguments</var> with
+    the following options:
+
+    *   To <a>create a worklet global scope</a> the user agent will return a new
+        {{StyleWorklet}}
+    *   To <a>lookup a class instance on a worklet global scope</a> given a
+        <var>workletGlobalScope</var> the user agent will return the result of
+        looking up <var>name</var> on the <var>workletGlobalScope</var>'s
+        <a>name map of apply hooks</a>.
+
+    If an exception is thrown then abort these steps.
 
+Issue: Need to deal with the output.
 
 Examples {#examples}
 ====================