[css-layout-api] Move LayoutChild around, add usage example.

Author: bfgeek

css-layout-api/Overview.bs

@@ -455,22 +455,40 @@ is called, the user agent <em>must</em> run the following steps:
         4. Otherwise, [=map/set=] |documentLayoutDefinitionMap|[|name|] to |documentDefinition|.
 </div>
 
-Layout API Model and Terminology {#layout-api-model-and-terminology}
-====================================================================
+Terminology {#terminology}
+--------------------------
 
-This section gives an overview of the Layout API given to authors.
+We define the following terms to be clear about which layout algorithm (formatting context) we are
+talking about.
 
-The <dfn>current layout</dfn> is the layout algorithm for the <a>box</a> we are currently performing
+The <dfn>current layout</dfn> is the layout algorithm for the [=box=] we are currently performing
 layout for.
 
-The <dfn>parent layout</dfn> is the layout algorithm for the <a>box's</a> direct parent, (the layout
-algorithm which is requesting the <a>current layout</a> to be performed).
+The <dfn>parent layout</dfn> is the layout algorithm for the [=box's=] direct parent, (the layout
+algorithm which is requesting the [=current layout=] to be performed).
+
+A <dfn>child layout</dfn> is the layout algorithm for a {{LayoutChild}} of the [=current layout=].
 
-A <dfn>child layout</dfn> is the layout algorithm for a {{LayoutChild}} of the <a>current layout</a>.
+Layout API {#layout-api}
+========================
+
+This section gives an overview of the Layout API given to authors.
 
 Layout Children {#layout-children}
 ----------------------------------
 
+A {{LayoutChild}} represents either a CSS generated [=box=] before layout has occurred. (The box
+or boxes will all have a computed value of 'display' that is not ''none'').
+
+The {{LayoutChild}} does not contain any layout information itself (like inline or block size) but
+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
+user agent rendering engine (post style resolution).
+
+An array of {{LayoutChild}}ren is passed into the layout/intrinsicSizes methods which represents the
+children of the current box which is being laid out.
+
 <pre class='idl'>
 [Exposed=LayoutWorklet]
 interface LayoutChild {
@@ -482,38 +500,57 @@ interface LayoutChild {
 </pre>
 
 The {{LayoutChild}} has internal slot(s):
-    - <dfn attribute for=LayoutChild>\[[box]]</dfn> a CSS <a>box</a>.
+    - <dfn attribute for=LayoutChild>\[[box]]</dfn> a CSS [=box=].
     - <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>
+<div class=example>
+The example below shows the basic usage of a {{LayoutChild}}.
+<pre class='lang-javascript'>
+registerLayout('example-layout-child', class {
+  static get childInputProperties() { return ['--foo']; }
 
-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'').
+  async layout(children, edges, constraints, styleMap) {
 
-The {{LayoutChild}} does not contain any layout information itself (like inline or block size) but
-can be used to generate {{LayoutFragment}}s which do contain layout information.
+    // An array of LayoutChildren is passed into both the layout function,
+    // and intrinsic sizes function below.
+    const child = children[0];
 
-An author cannot construct a {{LayoutChild}} with this API, this happens at a separate stage of the
-rendering engine (post style resolution).
+    // You can query the any properties listed in "childInputProperties".
+    const fooValue = child.styleMap.get('--foo');
+
+    // And perform layout!
+    const fragment = await child.layoutNextFragment({});
+
+  }
+
+  async intrinsicSizes(children, edges, styleMap) {
+
+    // Or request the intrinsic size!
+    const childIntrinsicSize = await children[0].intrinsicSizes();
+
+  }
+});
+</pre>
+</div>
 
 A {{LayoutChild}} could be generated by:
 
- - An <a>element</a>.
+ - An [=element=].
 
- - A <a>root inline box</a>.
+ - A [=root inline box=].
 
  - A <a>::before</a> or <a>::after</a> pseudo-element.
 
-    Note: Other pseudo-elements such as <a>::first-letter</a> or <a>::first-line</a> do not generate
-        a {{LayoutChild}} for layout purposes. They are additional styling information for a text
-        node.
+    Note: Other pseudo-elements such as <a>::first-letter</a> or <a>::first-line</a> do not
+        generate a {{LayoutChild}} for layout purposes. They are additional
+        styling information for a text node.
 
- - An <a>anonymous box</a>. For example an anonymous box may be inserted as a result of:
+ - An [=anonymous box=]. For example an anonymous box may be inserted as a result of:
 
-    - A text node which has undergone <a>blockification</a>. (Or more generally a <a>root inline
-        box</a> which has undergone <a>blockification</a>).
+    - A text node which has undergone [=blockification=]. (Or more generally a [=root inline box=]
+        which has undergone [=blockification=]).
 
     - An element with ''display: table-cell'' which doesn't have a parent with ''display: table''.
 
@@ -531,27 +568,24 @@ A {{LayoutChild}} could be generated by:
 
 <div class="note">
     Note: As an example the following would be placed into a single {{LayoutChild}} as they share a
-    <a>root inline box</a>:
+    [=root inline box=]:
     <pre class="lang-html">
         This is a next node, &lt;span>with some additional styling,
         that may&lt;/span> break over&lt;br>multiple lines.
     </pre>
 </div>
 
-Multiple non-<a>atomic inlines</a> are placed within the same {{LayoutChild}} to allow rendering
+Multiple non-[=atomic inlines=] are placed within the same {{LayoutChild}} to allow rendering
 engines to perform text shaping across element boundaries.
 
 <div class="note">
     Note: As an example the following should produce one {{LayoutFragment}} but is from
-    three non-<a>atomic inlines</a>:
+    three non-[=atomic inlines=]:
     <pre class="lang-html">
         &#x639;&lt;span style="color: blue">&#x639;&lt;/span>&#x639;
     </pre>
 </div>
 
-An array of {{LayoutChild}}ren is passed into the layout method which represents the children of the
-current box which is being laid out.
-
 <div algorithm>
 The <dfn attribute for=LayoutChild>styleMap</dfn>, on getting from a {{LayoutChild}} |this|, the
 user agent must perform the following steps:
@@ -586,8 +620,8 @@ Note: Both {{LayoutChild/layoutNextFragment()}} and {{LayoutChild/intrinsicSizes
 
 ### 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.
+Each [=box=] has a <dfn attribute for=box>\[[layoutChildMap]]</dfn> internal slot, which is a
+[=map=] 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