Specs: first draft at a more plausible StyleDeclarationList

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 244 matching lines @@
 Inline Styles
 -------------
 
 ```javascript
 partial class Element {
   readonly attribute StyleDeclarationList style;
 }
 
 class StyleDeclarationList {
   constructor ();
-  void add(StyleDeclaration styles, String? pseudoElement = null); // O(1) // in debug mode, throws if the dictionary has any properties that aren't registered
-  void remove(StyleDeclaration styles, String? pseudoElement = null); // O(N) in number of declarations
-  // TODO(ianh): Need to support inserting rules preserving order somehow
+
+  // There are two batches of styles in a StyleDeclarationList.
+
+  // The first batch is the per-frame styles. These get cleared each
+  // frame, after which all the matching rules in relevant <style> blocks
+  // get added back in, followed by all the animation-derived rules.
+  // Scripts can add styles themselves.
+  void addFrameStyles(StyleDeclaration styles, String? pseudoElement = null); // O(1)
+  void clearFrameStyles();
+
+  // The second batch is the persistent styles.
+  // Once added, they remain forever until removed.
+  void addPersistentStyles(StyleDeclaration styles, String? pseudoElement = null); // O(1)
+  void removePersistentStyles(StyleDeclaration styles, String? pseudoElement = null); // O(N) in number of declarations
+
+  // This returns all the frame styles followed by all the persistent styles, in insertion order.
   Array<StyleDeclaration> getDeclarations(String? pseudoElement = null); // O(N) in number of declarations
 }
 
 typedef StyleDeclaration Dictionary<ParsedValue>;
 ```
 
 Rule Matching
 -------------
 
 ```javascript
@@ skipping 39 matching lines @@
 be dropped from the render tree.
 
 If any node is removed in this pass relative to the previous pass, and
 it has an ownerLayoutManager, then call
 
 ```javascript
 node.ownerLayoutManager.release(node)
 ```
 
 ...to notify the layout manager that the node went away, then set the
-node's layoutManager and ownerLayoutManager attributes to null.
+node's ownerLayoutManager attribute to null.
 
 ```javascript
+partial class Element {
+  readonly attribute StyleNode? layout; // TODO(ianh): come up with a better name (sadly "style" is taken)
+   // this will be null until the first time it is rendered
+}
+
 callback any ValueResolver (any value, String propertyName, StyleNode node, Float containerWidth, Float containerHeight);
 
 class StyleNode {
   // this is generated before layout
   readonly attribute String text;
   readonly attribute Node? parentNode;
   readonly attribute Node? firstChild;
   readonly attribute Node? nextSibling;
 
   // access to the results of the cascade
+  // only works during layout and painting
   any getProperty(String name, String? pseudoElement = null);
+     // throw if this isn't during layout or painting
+     //   TODO(ianh): if the implementation of this does allow it to be queried the rest of the time too, relax this constraint
      // looking at the declarations for the given pseudoElement:
      // if there's a cached value, return it
      // otherwise, if there's an applicable ParsedValue, then
      //   if it has a resolver:
      //     call it
      //     cache the value
      //     if relativeDimension is true, then mark the value as provisional
      //     return the value
      //   otherwise use the ParsedValue's value; cache it; return it
      // otherwise, if a pseudo-element was specified, try again without one
@@ skipping 285 matching lines @@
 ```javascript
 { display: { value: sky.ErrorLayoutManager } }
 ```
 
 The ``div`` element doesn't have any default styles.
 
 These declarations are all shared between all the elements (so e.g. if
 you reach in and change the declaration that was added to a ``title``
 element, you're going to change the styles of all the other
 default-hidden elements).