Examples: move markAsLaidOut() to just before the return, so the asserts work

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 274 matching lines @@
   any state = null;
 }
 
 class StyleValueResolverSettings {
   // this is used as an "out" parameter for 'resolve()' below
   constructor(StyleValueResolverSettingsSettings initial);
   void reset(StyleValueResolverSettingsSettings initial);
     // sets firstTime and state to given values
     // sets layoutDependent to false
     // sets dependencies to empty set
+    // sets lifetime to Infinity
 
   readonly attribute Boolean firstTime;
     // true if this is the first time this property is being resolved for this element,
     // or if the last time it was resolved, the value was a different object
 
   // attribute Boolean layoutDependent
   void setLayoutDependent();
     // call this if the value should be recomputed each time the ownerLayoutManager's dimensions change, rather than being cached
   Boolean getLayoutDependent();
     // returns true if setLayoutDependent has been called since the last reset()
 
   // attribute "BitField" dependencies; // defaults to no bits set
   void dependsOn(PropertyHandle property);
     // if the given property doesn't have a dependency bit assigned:
     //  - assign the next bit to the property
     //  - if there's no bits left, throw
     // set the bit on this StyleValueResolverSettings's dependencies bitfield
   Array<PropertyHandle> getDependencies();
     // returns an array of the PropertyHandle values for the bits that are set in dependencies
 
+  // attribute (Float or Infinity) lifetime;
+  void setLifetime(Float age);
+    // if the new value is less than the current value of lifetime, update the current value
+  (Float or Infinity) getLifetime();
+    // return current value of lfietime
+
   attribute any state; // initially null, can be set to store value for this RenderNode/property pair
     // for example, TransitioningColorStyleValue would store
     //    {
     //      initial: /* color at time of transition */,
     //      target: /* color at end of transition */,
     //      start: /* time at start of transition */,
     //    }
     // ...which would enable it to update appropriately, and would also
     // let other transitions that come later know that you were half-way
     // through a transition so they can shorten their time accordingly
@@ skipping 136 matching lines @@
 
 ```javascript
 abstract class AbstractStyleDeclarationList {
   void addStyles(StyleDeclaration styles, String pseudoElement = ''); // O(1)
   void removeStyles(StyleDeclaration styles, String pseudoElement = ''); // O(N) in number of declarations
   Array<StyleDeclaration> getDeclarations(String pseudoElement = ''); // O(N) in number of declarations
 }
 
 class ElementStyleDeclarationList : AbstractStyleDeclarationList {
   constructor (Element? element);
+  readonly attribute Element? element;
 
   // there are two batches of styles in an ElementStyleDeclarationList.
 
   // the first batch is the per-frame styles; these get (conceptually)
   // 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 also add styles themselves, but they are
   // dropped after the next frame
   void addFrameStyles(StyleDeclaration styles, String pseudoElement = ''); // O(1)
   void clearFrameStyles();
 
   // the second batch is the persistent styles, which remain until removed;
   // they are accessed via the AbstractStyleDeclarationList accessors
 
   // as StyleDeclarations are added and removed, the ElementStyleDeclarationList
   // calls register(element) and unregister(element) respectively on those
   // StyleDeclaration objects, where element is the element that was passed
   // to the constructor, if not null
   // then, it calls element.renderNode.cascadedValueChanged
   // for each property on the object
 
   // the inherited getDeclarations() method returns all the frame
   // styles followed by all the persistent styles, in insertion order
 }
 
 class RenderNodeStyleDeclarationList : AbstractStyleDeclarationList {
   constructor (RenderNode? renderNode);
+  readonly attribute RenderNode? renderNode;
 
   // as StyleDeclarations are added and removed, the RenderNodeStyleDeclarationList
   // calls register(renderNode) and unregister(renderNode) respectively on those
   // StyleDeclaration objects, where renderNode is the RenderNode that was passed
   // to the constructor, if not null
   // then, it calls renderNode.cascadedValueChanged
   // for each property on the object
 }
 
 class StyleDeclaration {
@@ skipping 130 matching lines @@
   //    - pseudoElement, property => StyleValue object, resolved value, StyleValueResolverSettings, cascade dirty bit, value dirty bit
   // - property state map (initially empty), as follows:
   //    - pseudoElement, property => object
 
   any getProperty(PropertyHandle property, GetPropertySettings? settings = null);
      // looking at the cached data for the given pseudoElement:
      // if there's a cached value:
      //   if settings.forceCache is true, return the cached value
      //   if neither dirty bit is set, return the cached value
      //   if the cascade dirty bit is not set (value dirty is set) then
-     //     resolve the value using the same StyleValue object
-     //      - with firstTime=false on the resolver settings
-     //      - with the cached state object if any
-     //      - jump to "cache" below
+     //    - clear any pending lifetime-enforcing tasks for this
+     //      property/pseudoElement pair on this render node
+     //    - resolve the value using the same StyleValue object
+     //       - with firstTime=false on the resolver settings
+     //       - with the cached state object if any
+     //       - jump to "cache" below
      // if settings.forceCache is true, return null
+     // - clear any pending lifetime-enforcing tasks for this
+     //   property/pseudoElement pair on this render node
      // - if there's an override declaration with the property (with
-     //   the pseudo or without), then get the value object from there and
-     //   jump to "resolve" below.
-     // - if there's an element and it has a style declaration with the property
-     //   (with the pseudo or without), then get the value object from there
+     //   the pseudo or without), then get the value object from there
      //   and jump to "resolve" below.
-     // - if it's not an inherited property, or if there's no parent, then get the
-     //   default value and jump to "resolve" below.
-     // - call the parent render node's getProperty() with the same property
-     //   but no settings, then cache that value as the value for this element
-     //   with the given pseudoElement, with no StyleValue object, no resolver
-     //   settings, and set the state to null.
+     // - if there's an element and it has a style declaration with
+     //   the property (with the pseudo or without), then get the
+     //   value object from there and jump to "resolve" below.
+     // - if it's not an inherited property, or if there's no parent,
+     //   then get the default value and jump to "resolve" below.
+     // - call the parent render node's getProperty() with the same
+     //   property but no settings, then cache that value as the value
+     //   for this element with the given pseudoElement, with no
+     //   StyleValue object, no resolver settings, and set the state
+     //   to null.
      // resolve:
-     //   - get a new resolver settings object
-     //   - if the obtained StyleValue object is different than the
-     //     cached StyleValue object, or if there is no cached object, then set
-     //     the resolver settings to firstTime=true, otherwise it's the same object
-     //     and set firstTime=false.
-     //   - set the resolver settings' state to the current state for this
-     //     pseudoElement/property combination
+     //   - get a new resolver settings object (or reset an existing one)
+     //     - if the obtained StyleValue object is different than the
+     //       cached StyleValue object, or if there is no cached
+     //       object, then set the resolver settings to
+     //       firstTime=true, otherwise it's the same object and set
+     //       firstTime=false.
+     //     - set the resolver settings' state to the current state
+     //       for this pseudoElement/property combination
      //   - using the obtained StyleValue object, call resolve(),
      //     passing it this node and the resolver settings object.
      //   - jump to "cache" below
      // cache:
-     //   - update the cache with the obtained value and resolver settings
+     //   - update the cache with the obtained value and resolver
+     //     settings
      //   - reset the dirty bits
-     //   - if the resolver settings' getShouldSaveState() method returns false,
-     //     then discard any cached state, otherwise, cache the new state
+     //   - if the resolver settings' getShouldSaveState() method
+     //     returns false, then discard any cached state, otherwise,
+     //     cache the new state
+     //   - if the resolver settings' lifetime is not infinity, then
+     //     queue a lifetime-enforcing task for the appropriate time
+     //     in the future which calls cascadedValueDirty for this
+     //     property/pseudoElement pair on this render node
 
   readonly attribute RenderNodeStyleDeclarationList overrideStyles;
      // mutable; initially empty
      // this is used when isGhost is true, and can also be used more generally to
      // override styles from the layout manager (e.g. to animate a new node into view)
 
   private void cascadedValueChanged(PropertyHandle property, String pseudoElement = '');
   private void cascadedValueDirty(PropertyHandle property, String pseudoElement = '');
     // - set the appropriate dirty bit on the cached data for this property/pseudoElement pair
     //    - cascade dirty for cascadedValueChanged
@@ skipping 79 matching lines @@
 ```javascript
 callback LayoutManagerConstructor LayoutManager (RenderNode node);
 
 class LayoutManager : EventTarget {
   readonly attribute RenderNode node;
   constructor LayoutManager(RenderNode node);
     // sets needsManager to false on the node
 
   readonly attribute Boolean autoreap;
     // defaults to true
-    // when true, any children that are isNew are automatically welcomed by the default layout()
+    // when true, children that are added don't get set to isNew=true
     // when true, children that are removed don't get set to isGhost=true, they're just removed
 
   virtual Array<EventTarget> getEventDispatchChain(); // O(N) in number of this.node's ancestors // implements EventTarget.getEventDispatchChain()
     // let result = [];
     // let node = this.node;
     // while (node && node.layoutManager) {
     //   result.push(node.layoutManager);
     //   node = node.parentNode;
     // }
     // return result;
 
   void setProperty(RenderNode node, PropertyHandle property, any value, String pseudoElement = ''); // O(1)
-    // if called from an adjustProperties() method during the property adjustment phase,
     // replaces the value that getProperty() would return on that node with /value/
-    // this also clears the dependency bits and sets the property state to null
+    // this also clears the dependency bits, dirty bits, and sets the property state to null
+    // this also clears any relevant lifetime-enforcing tasks
 
   void take(RenderNode victim); // sets victim.ownerLayoutManager = this;
     // assert: victim hasn't been take()n yet during this layout
-    // assert: victim.needsLayout == true
     // assert: an ancestor of victim has node.layoutManager == this (aka, victim is a descendant of this.node)
 
   virtual void release(RenderNode victim);
     // called when the RenderNode was removed from the tree
 
   virtual void childAdded(RenderNode child);
   virtual void childRemoved(RenderNode child);
     // called when a child has its isNew or isGhost attributes set respectively
 
   void setChildPosition(child, x, y); // sets child.x, child.y
   void setChildX(child, y); // sets child.x
   void setChildY(child, y); // sets child.y
   void setChildSize(child, width, height); // sets child.width, child.height
   void setChildWidth(child, width); // sets child.width
   void setChildHeight(child, height); // sets child.height
+    // assert: child.ownerLayoutManager == this
     // for setChildSize/Width/Height: if the new dimension is different than the last assumed dimensions, and
     // any RenderNodes with an ownerLayoutManager==this have cached values for getProperty() that are marked
-    // as layout-dependent, clear them
-  void welcomeChild(child); // resets child.isNew
-  void reapChild(child); // resets child.isGhost
-
-  Generator<RenderNode> walkChildren();
-    // returns a generator that iterates over the children, skipping any whose ownerLayoutManager is not |this|
-
-  Generator<RenderNode> walkChildrenBackwards();
-    // returns a generator that iterates over the children backwards, skipping any whose ownerLayoutManager is not |this|
+    // as layout-dependent, mark them as dirty with cascadedValueDirty()
 
   void assumeDimensions(Float width, Float height);
-    // sets the assumed dimensions for calls to getProperty() on RenderNodes that have this as an ownerLayoutManager
+    // sets the assumed dimensions for calls to getProperty() on RenderNodes that have this as an ownerLayoutManager,
+    // by updating renderNode width/height;
     // if the new dimension is different than the last assumed dimensions, and any RenderNodes with an
-    // ownerLayoutManager==this have cached values for getProperty() that are marked as layout-dependent, clear them
-    // TODO(ianh): should we force this to match the input to layout(), when called from inside layout() and when
-    // layout() has a forced width and/or height?
+    // ownerLayoutManager==this have cached values for getProperty() that are marked as layout-dependent, mark them
+    // as dirty with cascadedValueDirty()
 
   virtual LayoutValueRange getIntrinsicWidth(Float? defaultWidth = null);
   /*
      function getIntrinsicWidth(defaultWidth) {
        if (defaultWidth == null) {
          defaultWidth = this.node.getProperty('width');
          if (typeof defaultWidth != 'number')
            defaultWidth = 0;
        }
        let minWidth = this.node.getProperty('min-width');
@@ skipping 37 matching lines @@
        if (defaultHeight < minHeight)
          defaultHeight = minHeight;
        return {
          minimum: minHeight,
          value: defaultHeight,
          maximum: maxHeight,
        };
      }
   */
 
+  void welcomeChild(child); // resets child.isNew
+  void reapChild(child); // resets child.isGhost
+
+  Generator<RenderNode> walkChildren();
+    // returns a generator that iterates over the children, skipping any whose ownerLayoutManager is not |this|
+
+  Generator<RenderNode> walkChildrenBackwards();
+    // returns a generator that iterates over the children backwards, skipping any whose ownerLayoutManager is not |this|
+
   void markAsLaidOut(); // sets this.node.needsLayout and this.node.descendantNeedsLayout to false
   virtual Dimensions layout(Float? width, Float? height);
-    // call markAsLaidOut();
-    // if autoreap is true: use walkChildren() to call welcomeChild() and reapChild() on each child
     // if width is null, set width to getIntrinsicWidth().value
-    // if height is null, set width height getIntrinsicHeight().value
+    // if height is null, set height to getIntrinsicHeight().value
     // call this.assumeDimensions(width, height);
     // call this.layoutChildren(width, height);
+    // call markAsLaidOut();
     // return { width: width, height: height }
-    // - this should always call this.markAsLaidOut() to reset needsLayout
-    // - the return value should include the final value for whichever of the width and height arguments
-    //   that is null
-    // - subclasses that want to make 'auto' values dependent on the children should override this
-    //   entirely, rather than overriding layoutChildren
+    // - this should always call this.markAsLaidOut() to reset
+    //   needsLayout and descendantNeedsLayout
+    // - the return value should include the final value for whichever
+    //   of the width and height arguments that is null
+    // - subclasses that want to make 'auto' values dependent on the
+    //   children should override this entirely, rather than
+    //   overriding layoutChildren; but see layoutChildren()'s notes
+    //   for how to do this
 
   virtual void layoutChildren(Float width, Float height);
     // default implementation does nothing
-    // - override this if you want to lay out children but not have the children affect your dimensions
+    // - override only this (and not layout()) if you want to lay out
+    //   children but not have the children affect your dimensions
+    // - always call setChildSize() and setChildPosition() after
+    //   calling a child's layout() method
+    // - if the child has needsLayout or if you need to have it
+    //   autosize, call its ownerLayoutManager's layout() method
+    // - otherwise if the child has needs descendantNeedsLayout, call
+    //   layoutDescendants()
+
+  virtual Dimensions layoutDescendants();
+    // assert: node.needsLayout is false, node.descendantNeedsLayout is true
+    // walk children:
+    //  - if it has needsLayout, call its layout() method with its
+    //    current width and height, then call setChildSize() with
+    //    those same dimensions
+    //  - else, if it has descendantNeedsLayout, call its
+    //    layoutDescendants() method
+    // call markAsLaidOut();
+    // - override this if you use take() to control more children, in
+    //   which case you should call their methods too
+    // - this should always call this.markAsLaidOut() to reset
+    //   needsLayout and descendantNeedsLayout
 
   virtual void paint(RenderingSurface canvas);
     // set a clip rect on the canvas for rect(0,0,this.width,this.height)
     //   (? we don't really have to do this; consider shadows...)
     // call the painter of each property, in order they were registered, which on this element has a painter
     // call this.paintChildren(canvas)
     // (the default implementation doesn't paint anything on top of the children)
     // unset the clip
     // - this gets called by the system if:
     //    - you are in your parent's current display list and it's in its parent's and so on up to the top, and
@@ skipping 94 matching lines @@
 ```
 
 The other elements don'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 ``span``
 element, you're going to change the styles of all the other
 default-hidden elements). (In other words, in the code snippets above,
 the ``d`` variable is initialised in shared code, and only the
 addStyles() call is per-element.)