apply-hook-ideas.txt

Introduction {#introduction}
============================

[[css-variables]] defines a new <<var()>> function that can be used to
insert the values of custom properties into other CSS property values. Where
possible, this mechanism should be preferred above the computed value modification
facilities of this specification.

Supported syntax strings {#supported-syntax-strings}
----------------------------------------------------

:   "&lt;'[property-name]'>", Where [property-name] is any existing CSS property
    name or any string that matches the <<custom-property-name>> production.
::  Any value that parses as a value of the specified property.


The apply hook {#the-apply-hook}
================================

<pre class='idl'>

interface ElementProxy {
  readonly attribute StylePropertyMapReadOnly inputStyle;
  readonly attribute StylePropertyMap outputStyle;
  readonly attribute DOMString? pseudo;
};

dictionary ApplyDescriptor {
  sequence&lt;DOMString&gt; inputProperties;
  sequence&lt;DOMString&gt; outputProperties;
};

callback VoidFunction = void ();

interface StyleWorklet : WorkletGlobalContext {
  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}
------------------------------------------------------------

{{ElementProxy}} objects represent the partial state of DOM objects that are
available to apply hooks running in <a>worklet global scope</a>s. They provide
the following attributes:

:   inputStyle
::  The set of styles that the apply hook has registered a dependency on.
:   outputStyle
::  The final result of running this apply hook.
:   pseudo
::  The pseudo name of the PseudoElement that this ElementProxy proxies, or
    null if this ElementProxy proxies an Element.

Issue(73): Do we need the pseudo attribute on ElementProxy for level 1?

Issue(74): Come up with a better name than ElementProxy. This is more of a computation context.

The {{ApplyDescriptor}} dictionary {#the-applydescriptor-dictionary}
--------------------------------------------------------------------

:   <dfn dict-member for=ApplyDescriptor>inputProperties</dfn>
::  The apply function is only called for elements or
    pseudoelements on which the listed properties all have non-initial values.

Issue(4): It should it be possible to access properties on the parent.

Issue(2): Should this be available only if explicitly requested in inputProperties?

:   <dfn dict-member for=ApplyDescriptor>outputProperties</dfn>
::  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}
----------------------------------------------------------------------

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?

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

Implementations may memoize the result of apply callbacks relative to the
complete set of inputs provided to apply (that is, the set of attributes on
{{ElementProxy}}).

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.

Note: Apply hooks run in parallel on a given Element. The output of an apply
hook is never used as input to another apply hook on the same Element - instead,
a snapshot of style state is taken, all apply hooks are run with subsets of the
same input snapshot, then the resulting output is written into the used style.

Examples {#examples}
====================

Example 1: Polyfill scale, translate, rotate {#example-1}
---------------------------------------------------------

<pre class='lang-markup'>
&lt;script&gt;
["--scale-x", "--scale-y"].forEach(function(name) {
document.registerProperty({
    name: name,
    syntax: "&lt;number&gt;",
    inherits: false,
    initialValue: "1"
  });
});

["--translate-x", "--translate-y"].forEach(function(name) {
  document.registerProperty({
    name: name,
    syntax: "&lt;length&gt;",
    inherits: false,
    initialValue: "0px"
  });
});

document.registerProperty({
  name: "--rotate",
  syntax: "&lt;angle&gt;",
  inherits: false,
  initialValue: "0deg"
});
&lt;/script&gt;
&lt;style&gt;

#myElement {
    --translate-x: 5px;
    --translate-y: 10px;
    --rotate: 10deg;
    --scale-x: 25;
    --scale-y: 25;
}

.foobar {
    --rotate: 20deg;
}
&lt;/style&gt;

&lt;script&gt;
this.registerApplyHook("transform-properties", class {
    apply(el) {
      el.outputStyle.set('transform', new TransformValue(
        [
          new Translation(el.inputStyle.get('--translate-x'),
                          el.inputStyle.get('--translate-y')),
          new Rotation(el.inputStyle.get('--rotate')),
          new Scale(el.inputStyle.get('--scale-x'),
                    el.inputStyle.get('--scale-y'))
        ].concat(el.inputStyle.get('transform'))));
    }}, {
      inputProperties: ["--translate-x", "--translate-y",
                        "--scale-x", "--scale-y",
                        "--rotate", "transform"],
      outputProperties: ["transform"]
    }
});
&lt;/script&gt;
</pre>