[css-layout-api] Firm up LayoutChild definition.

This includes proper internal slots for LayoutChild,
LayoutFragmentRequest, IntrinsicSizes request.

This also includes proper algorithms for all of LayoutChild.

Author: bfgeek

css-layout-api/Overview.bs

@@ -220,6 +220,14 @@ interface LayoutChild {
 };
 </pre>
 
+The {{LayoutChild}} has internal slot(s):
+    - <dfn attribute for=LayoutChild>\[[box]]</dfn> a CSS <a>box</a>.
+    - <dfn attribute for=LayoutChild>\[[styleMap]]</dfn> a {{StylePropertyMapReadOnly}}, this is the
+        computed style for the child, it is populated with only the properties listed in
+        <code>childInputProperties</code>.
+
+<hr>
+
 A {{LayoutChild}} represents either a CSS generated <a>box</a> before layout has occured. (The box
 or boxes will all have a computed value of 'display' that is not ''none'').
 
@@ -229,10 +237,6 @@ can be used to generate {{LayoutFragment}}s which do contain layout information.
 An author cannot construct a {{LayoutChild}} with this API, this happens at a separate stage of the
 rendering engine (post style resolution).
 
-The {{LayoutChild}} has computed style which can be accessed by {{LayoutChild/styleMap}}. The
-{{LayoutChild/styleMap}} will only contain properties which are listed in the child input properties
-array.
-
 A {{LayoutChild}} could be generated by:
 
  - An <a>element</a>.
@@ -284,17 +288,104 @@ engines to perform text shaping across element boundaries.
     </pre>
 </div>
 
-Note: In a future level of the specification there may be a way to query the computed style
-      of <a>inline boxes</a> inside a <a>root inline box</a> represented by a {{LayoutChild}}.
-
 An array of {{LayoutChild}}ren is passed into the layout method which represents the children of the
 current box which is being laid out.
 
-To perform layout on a box the author can invoke the {{LayoutChild/layoutNextFragment()}} method.
-This will produce a {{LayoutFragment}} which contains layout information.
+<div algorithm>
+The <dfn attribute for=LayoutChild>styleMap</dfn>, on getting from a {{LayoutChild}} |this|, the
+user agent must perform the following steps:
+
+    1. Return |this|' {{StylePropertyMapReadOnly}} contained in the {{[[styleMap]]}} internal slot.
+</div>
+
+<div algorithm>
+When the <dfn method for=LayoutChild>layoutNextFragment(|constraints|, |breakToken|)</dfn> method is
+called on a {{LayoutChild}} |this|, the user agent must perform the following steps:
+
+    1. Let |request| be a new {{LayoutFragmentRequest}} with internal slot(s):
+        - {{LayoutFragmentRequest/[[layoutChild]]}} set to |this|.
+        - {{[[layoutConstraints]]}} set to |constraints|.
+        - {{[[breakToken]]}} set to |breakToken|.
+
+    2. Return |request|.
+</div>
+
+<div algorithm>
+When the <dfn method for=LayoutChild>intrinsicSizes()</dfn> method is called on a {{LayoutChild}}
+|this|, the user agent must perform the following steps:
+
+    1. Let |request| be a new {{IntrinsicSizesRequest}} with internal slot(s):
+          - {{IntrinsicSizesRequest/[[layoutChild]]}} set to |this|.
+
+    2. Return |request|.
+</div>
+
+Note: Both {{LayoutChild/layoutNextFragment()}} and {{LayoutChild/intrinsicSizes()}} don't
+    synchronously run. See [[#request-objects]] for a full description.
+
+### LayoutChildren and the Box Tree ### {#layout-child-box-tree}
+
+Each <a>box</a> has a <dfn attribute for=box>\[[layoutChildMap]]</dfn> internal slot, which is a <a>map</a> of
+{{LayoutWorkletGlobalScope}}s to {{LayoutChild}}ren.
+
+<div algorithm="get a layout child">
+When the user agent wants to <dfn>get a layout child</dfn> given |workletGlobalScope|, |name|, and
+|box|, it <em>must</em> run the following steps:
+
+    1. Assert that:
+        - |box| is currently attached to the <a>box tree</a>.
+        - |box|'s <a>containing block</a> is a <a>layout API container</a>.
+        - The <a>containing block</a>'s ''layout()'' function's first argument is |name|.
+
+    2. Let |layoutChildMap| be |box|'s {{[[layoutChildMap]]}}.
+
+    3. If |layoutChildMap|[|workletGlobalScope|] does not <a for=map>exist</a>, run the following
+        steps:
 
-The {{LayoutChild/layoutNextFragment()}} method may be invoked multiple times with different
-arguments to query the {{LayoutChild}} for different layout information.
+        1. Let |definition| be the result of <a>get a layout definition</a> given |name|, and
+            |workletGlobalScope|.
+
+        2. Let |childInputProperties| be |definition|'s <a for="layout definition">child input
+            properties</a>.
+
+        3. Let |layoutChild| be a new {{LayoutChild}} with internal slot(s):
+            - {{[[box]]}} set to |box|.
+            - {{[[styleMap]]}} set to a new {{StylePropertyMapReadOnly}} populated with
+                <em>only</em> the <a>computed values</a> for properties listed in
+                |childInputProperties|.
+
+        4. <a for=map>Set</a> |layoutChildMap|[|workletGlobalScope|] to |layoutChild|.
+
+    4. Return the result of <a for=map>get</a> |layoutChildMap|[|workletGlobalScope|]
+</div>
+
+When a <a>box</a> is inserted into the <a>box tree</a> the user agent <em>may</em> pre-populate the
+{{[[layoutChildMap]]}} for all {{LayoutWorkletGlobalScope}}s.
+
+When a <a>box</a> is removed from the <a>box tree</a> the user agent <em>must</em> clear the
+{{[[layoutChildMap]]}}.
+
+<div algorithm="update a layout child style">
+When the user agent wants to <dfn>update a layout child style</dfn> given |box|, it <em>must</em>
+run the following steps:
+
+    1. Assert that:
+        - |box| is currently attached to the <a>box tree</a>.
+
+    2. If |box|'s <a>containing block</a> is not a <a>layout API container</a>, abort all these
+        steps.
+
+    3. Let |layoutChildMap| be |box|'s {{[[layoutChildMap]]}}.
+
+    4. <a for=map>For each</a> |layoutChild| in |layoutChildMap|:
+
+        1. Let |styleMap| be |layoutChild|'s {{[[styleMap]]}}.
+
+        2. Update |styleMap|'s <a>declarations</a> based on the |box|'s new computed style.
+</div>
+
+When the computed style of a <a>box</a> changes the user agent must run the <a>update a layout child
+style</a> algorithm.
 
 Layout Fragments {#layout-fragments}
 ------------------------------------
@@ -1047,7 +1138,7 @@ Concepts {#concepts}
 --------------------
 
 A <dfn>layout definition</dfn> is a <a>struct</a> which describes the information needed by the
-{{LayoutWorkletGlobalScope}} about hte author defined layout (which can be referenced by the
+{{LayoutWorkletGlobalScope}} about the author defined layout (which can be referenced by the
 ''layout()'' function). It consists of:
 
  - <dfn for="layout definition">class constructor</dfn> which is the class <a>constructor</a>.
@@ -1371,23 +1462,33 @@ Layout Engine {#layout-engine}
      - Potentially better bindings overhead.
 </div>
 
+### Request Objects ### {#request-objects}
 
 <pre class="idl">
 [Exposed=LayoutWorklet]
-interface LayoutFragmentRequest {
-  // Has internal slots:
-  // [[layoutChild]] - The layout child to generate the fragment for.
-  // [[layoutConstraints]] - The layout constraints object to perform layout in.
-  // [[breakToken]] - The break token to resume the layout with.
+interface IntrinsicSizesRequest {
 };
 
 [Exposed=LayoutWorklet]
-interface IntrinsicSizesRequest {
-  // Has internal slots:
-  // [[layoutChild]] - The layout child to calculate the intrinsic sizes for.
+interface LayoutFragmentRequest {
 };
 </pre>
 
+The {{IntrinsicSizesRequest}} has internal slot(s):
+    - <dfn attribute for=IntrinsicSizesRequest>\[[layoutChild]]</dfn> a {{LayoutChild}}, this is the
+        child which the intrinsic sizes must be calculated for.
+
+The {{LayoutFragmentRequest}} has internal slot(s):
+    - <dfn attribute for=LayoutFragmentRequest>\[[layoutChild]]</dfn> a {{LayoutChild}}, this is the
+        child which the fragment must be generated for.
+    - <dfn attribute for=LayoutFragmentRequest>\[[layoutConstraints]]</dfn> a
+        {{LayoutConstraintsOptions}} dictionary, these are the input constraints to the
+        {{LayoutChild}}'s layout algorithm.
+    - <dfn attribute for=LayoutFragmentRequest>\[[breakToken]]</dfn> a {{ChildBreakToken}} object,
+        which is the break token the layout must be resumed with.
+
+<hr>
+
 The layout method and intrinsic sizes method on the author supplied layout class is a generator
 function instead of a regular javascript function. This is for user-agents to be able to support
 asynchronous and parallel layout engines.