[css-layout-api] Firm up invalidation section, reorder concepts section.

Author: bfgeek

css-layout-api/Overview.bs

@@ -960,57 +960,6 @@ Layout {#layout}
 
 This section describes how the CSS Layout API interacts with the user agent's layout engine.
 
-Layout Invalidation {#layout-invalidation}
-------------------------------------------
-
-A <a>document</a> has an associated <dfn>layout name to input properties map</dfn> and a <dfn>layout
-name to child input properties map</dfn>. Initially these maps are empty and are populated when
-{{registerLayout(name, layoutCtor)}} is called.
-
-Each <a>box</a> has an associated <dfn>layout valid flag</dfn>. It may be either
-<dfn>layout-valid</dfn> or <dfn>layout-invalid</dfn>. It is initially set to <a>layout-invalid</a>.
-
-Each <a>box</a> has an associated <dfn>intrinsic sizes valid flag</dfn>. If may be either
-<dfn>intrinsic-sizes-valid</dfn> or <dfn>intrinsic-sizes-invalid</dfn>. It is initially set to
-<a>intrinsic-sizes-invalid</a>.
-
-When the computed style for a |box| changes, the user agent must run the following steps:
-    1. Let |layoutFunction| be the ''layout()'' function of the 'display' property on the computed
-        style for the |box| if it exists. If it is a different type of value (e.g.  ''grid'') then
-        abort all these steps.
-
-    2. Let |name| be the first argument of the |layoutFunction|.
-
-    3. Let |inputProperties| be the result of looking up |name| on <a>layout name to input
-        properties map</a>.
-
-    4. Let |childInputProperties| be the result of looking up |name| on <a>layout name to child
-        input properties map</a>.
-
-    5. For each |property| in |inputProperties|, if the |property|'s <a>computed value</a> has
-        changed, set the <a>layout valid flag</a> on the <a>box</a> to <a>layout-invalid</a>, and
-        set the <a>intrinsic sizes valid flag</a> to <a>intrinsic-sizes-invalid</a>.
-
-    6. For each |property| in |childInputProperties|, if the |property|'s <a>computed value</a> has
-        changed, set the <a>layout valid flag</a> on the <a>box</a> to <a>layout-invalid</a>, and
-        set the <a>intrinsic sizes valid flag</a> to <a>intrinsic-sizes-invalid</a>.
-
-When a child <a>box</a> represented by a {{LayoutChild}} is added or removed from the <a>box
-tree</a> or has its layout invalidated (from a computed style change, or a descentdant change). Set
-the <a>layout valid flag</a> on the current <a>box</a> to <a>layout-invalid</a> and set the
-<a>intrinsic sizes valid flag</a> on the current <a>box</a> to <a>intrinsic-sizes-invalid</a>.
-
-Note: This only describes layout invalidation as it relates to the CSS Layout API. All
-    <a>boxes</a> conceptually have a <a>layout valid flag</a> and these changes are propagated
-    through the <a>box tree</a>.
-
-Issue: We also want to implcitly invalidate on size and edge properties, i.e.
-    - 'width', 'min-width', 'max-width'
-    - 'height', 'min-height', 'max-height'
-    - 'padding-top', 'padding-bottom', 'padding-left', 'padding-right'
-    - 'border-top-width', 'border-bottom-width', 'border-left-width', 'border-right-width'
-    - 'overflow', 'overflow-x', 'overflow-y'
-
 Concepts {#concepts}
 --------------------
 
@@ -1048,6 +997,80 @@ function). It consists of:
 
  - <dfn for="document layout definition">layout options</dfn> a {{LayoutOptions}}.
 
+Layout Invalidation {#layout-invalidation}
+------------------------------------------
+
+Each <a>box</a> has an associated <dfn>layout valid flag</dfn>. It may be either
+<dfn>layout-valid</dfn> or <dfn>layout-invalid</dfn>. It is initially set to <a>layout-invalid</a>.
+
+Each <a>box</a> has an associated <dfn>intrinsic sizes valid flag</dfn>. If may be either
+<dfn>intrinsic-sizes-valid</dfn> or <dfn>intrinsic-sizes-invalid</dfn>. It is initially set to
+<a>intrinsic-sizes-invalid</a>.
+
+<div algorithm>
+When the user agent wants to <dfn>invalidate layout functions</dfn> given |box|, the user agent
+<em>must</em> run the following steps:
+
+    1. Let |layoutFunction| be the ''layout()'' function of the 'display' property on the computed
+        style for the |box| if it exists. If it is a different type of value (e.g.  ''grid'') then
+        abort all these steps.
+
+    2. Let |name| be the first argument of the |layoutFunction|.
+
+    3. Let |documentDefinition| be the result of <a>get a document layout definition</a> given
+        |name|.
+
+    4. Let |inputProperties| be |documentDefinition|'s <a for="document layout definition">input
+        properties</a>.
+
+    5. Let |childInputProperties| be |documentDefinition|'s <a for="document layout
+        definition">child input properties</a>.
+
+    6. For each |property| in |inputProperties|, if the |property|'s <a>computed value</a> has
+        changed, set the <a>layout valid flag</a> on the <a>box</a> to <a>layout-invalid</a>, and
+        set the <a>intrinsic sizes valid flag</a> to <a>intrinsic-sizes-invalid</a>.
+
+    7. For each |property| in |childInputProperties|, if the |property|'s <a>computed value</a> has
+        changed, set the <a>layout valid flag</a> on the <a>box</a> to <a>layout-invalid</a>, and
+        set the <a>intrinsic sizes valid flag</a> to <a>intrinsic-sizes-invalid</a>.
+</div>
+
+<a>Invalidate layout functions</a> <em>must</em> be run when the user agent recalculates the computed
+style for a box, or when the children's computed style of that box is recalculated.
+
+When a child <a>box</a> represented by a {{LayoutChild}} is added or removed from the <a>box
+tree</a> or has its layout invalidated (from a computed style change, or a descendant change),
+<em>and</em> this invalidation is to be propagated up the box tree, set the <a>layout valid flag</a>
+on the current <a>box</a> to <a>layout-invalid</a> and set the <a>intrinsic sizes valid flag</a> on
+the current <a>box</a> to <a>intrinsic-sizes-invalid</a>.
+
+When the computed style of a <a>layout API container</a> changes, <em>and</em> this change effects
+the values inside the {{LayoutEdges}} object, set the <a>layout valid flag</a> of the box to
+<a>layout-invalid</a>, and set the <a>intrinsic sizes valid flag</a> of the box to
+<a>intrinsic-sizes-invalid</a>.
+
+If the computed style changes effects the values inside the {{LayoutConstraints}} object, just set
+the <a>intrinsic sizes valid flag</a> of the box to <a>intrinsic-sizes-invalid</a>.
+
+Note: As the {{LayoutConstraints}} object is only passed into the layout function there is no need
+    to invalidate the intrinsic sizes.
+
+<div class="note">
+    Note: As an example the following properties could change the {{LayoutEdges}} object:
+        - 'padding-top'
+        - 'border-left-width'
+        - 'overflow-y'
+
+    And the following properties could change the {{LayoutConstraints}} object:
+        - 'width'
+        - 'max-width'
+        - 'height'
+</div>
+
+Note: This only describes layout invalidation as it relates to the CSS Layout API. All
+    <a>boxes</a> conceptually have a <a>layout valid flag</a> and these changes are propagated
+    through the <a>box tree</a>.
+
 Layout Worklet {#layout-worklet}
 --------------------------------