Specs: add a way to give layout managers alternative sets of properties so that they can make confi…

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 124 matching lines @@
 
 Sky Style uses whatever SelectorQuery. Maybe one day we'll make
 SelectorQuery support being extended to support arbitrary selectors,
 but for now, it supports:
 
    tagname
    #id
    .class
    [attrname]
    [attrname=value]
-   :host
+   :host                  ("host" string is fixed)
+   ::pseudo-element
 
-These can be combined (without whitespace), with at most one tagname,
-as in:
+These can be combined (without whitespace), with at most one tagname
+(must be first) and at most one pseudo-element (must be last) as in:
 
-   tagname[attrname]#id:host.class.class[attrname=value]
+   tagname[attrname]#id:host.class.class[attrname=value]::foo
 
 In debug mode, giving two IDs, or the same selector twice (e.g. the
 same classname), or specifying other redundant or conflicting
 selectors (e.g. [foo][foo=bar], or [foo=bar][foo=baz]) will be
 flagged.
 
-Alternatively, a selector can be the following special value:
+Alternatively, a selector can be the special value "@document",
+optionally followed by a pseudo-element, as in:
 
-   @document
+   @document::bar
 
 
 Value Parser
 ------------
 
   class StyleToken {
     constructor (String king, String value);
     readonly attribute String kind;
        // string
        // identifier
@@ skipping 75 matching lines @@
 
 Inline Styles
 -------------
 
 partial class Element {
   readonly attribute StyleDeclarationList style;
 }
 
 class StyleDeclarationList {
   constructor ();
-  void add(StyleDeclaration styles); // O(1) // in debug mode, throws if the dictionary has any properties that aren't registered
-  void remove(StyleDeclaration styles); // O(N) in number of declarations
-  Array<StyleDeclaration> getDeclarations(); // O(N) in number of declarations
+  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
+  Array<StyleDeclaration> getDeclarations(String? pseudoElement = null); // O(N) in number of declarations
 }
 
 typedef StyleDeclaration Dictionary<ParsedValue>;
 
 
 Rule Matching
 -------------
 
 partial class StyleElement {
   Array<Rule> getRules(); // O(N) in rules
 }
 
 class Rule {
   constructor ();
   attribute SelectorQuery selector; // O(1)
+  attribute String? pseudoElement; // O(1)
   attribute StyleDeclaration styles; // O(1)
 }
 
 Each frame, at some defined point relative to requestAnimationFrame():
- - If a rule starts applying to an element, sky:core calls thatElement.style.add(rule.styles);
- - If a rule stops applying to an element, sky:core calls thatElement.style.remove(rule.styles);
+ - If a rule starts applying to an element, sky:core calls thatElement.style.add(rule.styles, rule.pseudoElement);
+ - If a rule stops applying to an element, sky:core calls thatElement.style.remove(rule.styles, rule.pseudoElement);
 
 
 Cascade
 -------
 
 For each Element, the StyleDeclarationList is conceptually flattened
 so that only the last declaration mentioning a property is left.
 
 Create the flattened render tree as a tree of StyleNode objects
 (described below). For each one, run the equivalent of the following
@@ skipping 18 matching lines @@
   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
-    any getProperty(String name);
+    any getProperty(String name, String? pseudoElement = null);
+       // 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
        // otherwise, if the property is inherited and there's a parent:
-       //   get it from the parent; cache it; return it
+       //   get it from the parent (without pseudo); cache it; return it
        // otherwise, get the default value; cache it; return it
 
     readonly attribute Boolean needsLayout; // means that a property with needsLayout:true has changed on this node or one of its descendants
     readonly attribute LayoutManager layoutManager;
 
     readonly attribute LayoutManager ownerLayoutManager; // defaults to the parentNode.layoutManager
       // if you are not the ownerLayoutManager, then ignore this StyleNode in layout() and paintChildren()
       // using walkChildren() does this for you
 
     readonly attribute Boolean needsPaint; // means that either needsLayout is true or a property with needsPaint:true has changed on this node or one of its descendants
@@ skipping 163 matching lines @@
 * ``error``
   This adds to itself the declaration with value:
   ``{ 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).