Specs: Tentative approach for enabling removing/adding/moving children

sky/specs/style.md

 Sky Style Language
 ==================
 
 Planed changes
 --------------
 
 Add //-to-end-of-line comments to be consistent with the script
 language.
 
 
@@ skipping 178 matching lines @@
   constructor (Array<StyleToken> tokens);
   IteratorResult next();
   TokenSourceBookmark getBookmark();
   void rewind(TokenSourceBookmark bookmark);
 }
 class TokenSourceBookmark {
   constructor ();
   // TokenSource stores unforgeable state on this object using symbols or a weakmap or some such
 }
 
+// TODO(ianh): this is a non-starter, we need something better to handle units and custom painting
 dictionary ParsedValue {
   any value = null;
   ValueResolver? resolver = null;
   Boolean relativeDimension = false; // if true, e.g. for % lengths, the callback will be called again if an ancestor's dimensions change
   Painter? painter = null;
 }
 
 // best practice convention: if you're creating a property with needsPaint, you should 
 // create a new style value type for it so that it can set the paint callback right;
 // you should never use such a style type when parsing another property
@@ skipping 177 matching lines @@
   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
 
   // only the ownerLayoutManager can change these
   readonly attribute Float x; // relative to left edge of ownerLayoutManager
   readonly attribute Float y; // relative to top edge of ownerLayoutManager
   readonly attribute Float width;
   readonly attribute Float height;
+  readonly attribute Boolean isNew; // node has just been added (and maybe you want to animate it in)
+  readonly attribute Boolean isGhost; // node has just been removed (and maybe you want to animate it away)
 }
 ```
 
 The flattened tree is represented as a hierarchy of Node objects. For
 any element that only contains text node children, the "text" property
 is set accordingly. For elements with mixed text node and non-text
 node children, each run of text nodes is represented as a separate
 Node with the "text" property set accordingly and the styles set as if
 the Node inherited everything inheritable from its parent.
 
@@ skipping 27 matching lines @@
 - 'none': null
 
 
 Layout managers inherit from the following API:
 
 ```javascript
 class LayoutManager : EventTarget {
   readonly attribute StyleNode node;
   constructor LayoutManager(StyleNode node);
 
+  readonly attribute Boolean autoreap;
+    // defaults to true
+    // when true, any children that are isNew or isGhost are welcomed/reaped implicitly by default layout()
+
   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 take(StyleNode 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(StyleNode victim);
     // called when the StyleNode was removed from the tree
 
   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
     // for setChildSize/Width/Height: if the new dimension is different than the last assumed dimensions, and
     // any StyleNodes with an ownerLayoutManager==this have cached values for getProperty() that are marked
     // as provisional, clear them
+  void welcomeChild(child); // resets child.isNew
+  void reapChild(child); // resets child.isGhost
 
   Generator<StyleNode> walkChildren();
     // returns a generator that iterates over the children, skipping any whose ownerLayoutManager is not |this|
 
   Generator<StyleNode> walkChildrenBackwards();
     // returns a generator that iterates over the children backwards, skipping any whose ownerLayoutManager is not |this|
 
   void assumeDimensions(Float width, Float height);
     // sets the assumed dimensions for calls to getProperty() on StyleNodes that have this as an ownerLayoutManager
     // if the new dimension is different than the last assumed dimensions, and any StyleNodes with an
@@ skipping 53 matching lines @@
          minimum: minHeight,
          value: defaultHeight,
          maximum: maxHeight,
        };
      }
   */
 
   void markAsLaidOut(); // sets this.node.needsLayout and this.node.descendantNeedsLayout to false
   virtual Dimensions layout(Number? width, Number? 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
     // call this.assumeDimensions(width, height);
     // call this.layoutChildren(width, height);
     // 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
@@ skipping 116 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).