[css-property-values-api] fleshed out description of registerProperty and registerApplyHook.

Author: shans

css-properties-values-api/Overview.bs

@@ -10,6 +10,7 @@ Editor: Shane Stephens, shanestephens@google.com
 Editor: Daniel Glazman, daniel.glazman@disruptive-innovations.com
 Editor: Elliot Sprehn, esprehn@chromium.org
 Editor: Greg Whitworth, gwhit@microsoft.com
+Ignored Terms: boolean, Animatable, Map 
 </pre>
 
 Introduction
@@ -26,21 +27,90 @@ dictionary PropertyDescriptor {
   DOMString initialValue;
 };
 
-partial interface Document {
+partial interface CSS {
   void registerProperty(PropertyDescriptor descriptor);
+  void unregisterProperty(DOMString name);
 };
 </pre>
 
+Issue: CSS? Document?
 
+:   <dfn dict-member for=PropertyDescriptor>name</dfn>
+::  The name of the custom property being defined. This must begin with a double dash ('--').
+
+:   <dfn dict-member for=PropertyDescriptor>syntax</dfn>
+::  A string representing how this custom property is parsed. Only
+    simple type references are supported.
+
+    Note: for example, the syntax string could be '<length>' or '<number>'.
+
+    Note: in future levels we anticipate supporting more sophisticated parse strings, e.g.
+    '<length> || <number>'
+
+:   <dfn dict-member for=PropertyDescriptor>inherits</dfn>
+::  True if this custom property should inherit down the DOM tree; False otherwise.
+
+:   <dfn dict-member for=PropertyDescriptor>initialValue</dfn>
+::  The initial value of this custom property.
+
+When a custom property is registered with a given type, its computed value is defined
+fully by the type selected. Furthermore, the property will interpolate in a manner
+defined for that type by [[css3-animations]].
+
+TODO: Actually work out whether we need to describe computation per type
+here, or whether we can crib from another spec.
+
+If {{registerProperty()}} is called with a descriptor name that matches an already registered property,
+then an exception is thrown and the re-registration fails.
+
+Properties can be unregistered using {{unregisterProperty()}}. If this function is called with a name
+that doesn't match an existing property then an exception is thrown.
+
+Calls to both {{registerProperty()}} and {{unregisterProperty()}} trigger a reparse of all parsed CSS.
 
 The apply hook
 ==============
 
+<pre class='idl'>
 
-<div class='notes'>
+interface StyleWriter {
+  // affordances for writing to used values, but only those in outputProperties
+};
+
+callback ApplyCallback = void (Animatable element, StyleWriter writer, Map<DOMString, any> computedValues);
 
-syntax: is a string, doesn't accept anything for V1 except '<a single type here>' (e.g. <length>).
-Specifically: <length>, <color>, <number>, <angle>, <url>, <image>, <position>, <transform>
+dictionary ApplyDescriptor {
+  ApplyCallback applyHook;
+  sequence&lt;DOMString&gt;? inputProperties;
+  sequence&lt;DOMString&gt; outputProperties;
+};
+
+partial interface CSS {
+  long registerApplyHook(ApplyDescriptor apply);
+  void unregisterApplyHook(long hookID);
+};
+</pre>
+
+Issue: CSS? Document?
+
+
+:   <dfn dict-member for=ApplyDescriptor>inputProperties</dfn>
+::  If this value is not null, then the apply function is only called for elements or
+    pseudoelements on which the listed properties all have non-initial values.
+
+:   <dfn dict-member for=ApplyDescriptor>outputProperties</dfn>
+::  This value defines the properties for which the apply function can modify the used
+    value.
+
+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.
+
+
+<pre class='note'>
+
+syntax: is a string, doesn't accept anything for V1 except '&lt;a single type here&gt;' (e.g. &lt;length&gt;).
+Specifically: &lt;length&gt;, &lt;color&gt;, &lt;number&gt;, &lt;angle&gt;, &lt;url&gt;, &lt;image&gt;, &lt;position&gt;, &lt;transform&gt;
 type: not needed for V1 (because it's derived from syntax).
 animation: not needed for V1 (because it's derived from syntax).
 
@@ -49,15 +119,15 @@ Limitation: can't have percentages without a computation hook.
 Does invalidation go here?
 
 What does this give us:
-(1) the ability to feed typed information to custom paint/layout
-(2) the ability to animate custom properties
+1.  the ability to feed typed information to custom paint/layout
+2.  the ability to animate custom properties
 
 Things that are missing:
-(1) there's no way to define a custom computation - i.e. we can take '33em' to '330px' in the standard way, but
+1.  there's no way to define a custom computation - i.e. we can take '33em' to '330px' in the standard way, but
     we can't convert '33em' to something special.
-(2) there's no way to define custom animation. So we can't register for strings and define some crazy way
+2.  there's no way to define custom animation. So we can't register for strings and define some crazy way
     to animate them.
-(3) there's no way (outside of direct var references or custom painters/layouters) for the custom properties
+3.  there's no way (outside of direct var references or custom painters/layouters) for the custom properties
     to impact layout or paint. This is 'applying the value', and refers to manipulating the used value of
     other properties.
 
@@ -151,4 +221,4 @@ registerProperty({
 });
 </script>
 
-
+</pre>