[motion-1] Simplify the behavior of the 'contain' keyword. #363

w3c · Mar 7, 2023 · bd9fb9b · bd9fb9b
1 parent 916b4fa
commit bd9fb9b
Showing 1 changed file with 29 additions and 5 deletions.
diff --git a/motion-1/Overview.bs b/motion-1/Overview.bs
@@ -310,13 +310,37 @@ Its arguments are:
 
     : <dfn>contain</dfn>
     ::
-        The used value of 'offset-distance' is clamped so that the box is entirely contained within the path.
-
-        If no 'offset-distance' would lead to the box being enclosed by the path, the path size is minimally increased so that such an 'offset-distance' exists.
-
-        Issue: Not clear what this actually means. See <a href="https://github.com/w3c/fxtf-drafts/issues/363">Issue 363</a>.
+        The length of the [=offset path=] is reduced
+        so that the element stays within the [=containing block=]
+        even at ''offset-distance: 100%''.
+
+        Specifically, the path's length is reduced
+        by half the width or half the height of the element's border box,
+        whichever is larger,
+        and floored at zero.
+
+        <div class=note>
+            This behavior is optimized for a particular case--
+            the element's width and height are equal or nearly so;
+            the element is either completely rounded by 'border-radius'
+            or the corners aren't relevant to its appearance;
+            the ''ray()'' uses ''closest-side'' positioning;
+            and 'anchor-position' is set to ''center''.
+
+            Under these conditions,
+            which are common for situations
+            like positioning elements around the edge of a round clock face,
+            this ensures that each element is positioned
+            fairly snugly against the inner edge of the clock face
+            at ''offset-distance: 100%''.
+
+            In other conditions this will act <em>similarly</em>
+            but might not give quite as optimal a result.
+        </div>
 </dl>
 
+Issue: all of these examples need to be rewritten.
+
 <div class=example>
     Here are some examples. The first example shows that some parts of boxes are outside of the <a>offset path</a>.
     <pre><code highlight=html>