[motion-1] Per WG resolution, add offset-position:normal that doesn't override the normal position defaulting, and add an 'at ' to ray(). #504

Author: tabatkins

motion-1/Overview.bs

@@ -165,7 +165,7 @@ Values have the following meanings:
     : <>
     ::
         The [=offset path=] is a line
-        extending from the [=offset starting position=]
+        extending from the [=ray()/origin=]
         at some angle.
         See [[#ray-function]] for details.
 
@@ -197,10 +197,14 @@ Values have the following meanings:
         The [=offset path=] is the [=<basic-shape>/equivalent path=]
         of the <> function.
 
-        If ''circle()'' or ''ellipse()'' is used,
-        and an explicit center position is not given,
-        they default to using the [=offset starting position=],
-        rather than their standard default.
+        For all <>s,
+        if they accept an ''at <>'' argument
+        but that argument is omitted,
+        and the element defines an [=offset starting position=]
+        via 'offset-position',
+        it uses the specified [=offset starting position=]
+        for that argument.
+        Otherwise it defaults as specified for each function.
 
         The <> provides the [=/reference box=]
         for the <>.
@@ -236,7 +240,7 @@ The ''ray()'' function defines an [=offset path=]
 as a straight line emerging from a point at some defined angle:
 
 
-ray() = ray( <> && <>? && contain? )
+ray() = ray( <> && <>? && contain? && [at <>]? )
 
 <ray-size> = closest-side | closest-corner | farthest-side | farthest-corner | sides
 
@@ -338,6 +342,28 @@ Its arguments are:
             In other conditions this will act similarly
             but might not give quite as optimal a result.
         
+
+    : at <>
+    ::
+        Specifies the origin of the ray,
+        where the ray's line begins
+        (the 0% position).
+        It's resolved by using the <>
+        to position a 0x0 object area
+        within the box's [=containing block=].
+
+        If omitted, it uses the [=offset starting position=]
+        of the element,
+        given by 'offset-position'.
+
+        If the element doesn't have an [=offset starting position=] either,
+        it behaves as ''at center''.
+
+        Note: ''ray()'' is currently only usable as an [=offset path=].
+        If it ever gets extended to other uses,
+        its usage of 'offset-position'
+        will be limited solely to when it's an [=offset path=],
+        similar to other <> functions.
 
 
 Issue: all of these examples need to be rewritten.
@@ -752,34 +778,38 @@ Starting Point Of The Path: the 'offset-position' property {#offset-position-pro
 
 
 Name: offset-position
-Value: auto | <>
+Value: normal | auto | <>
 Initial: auto
 Media: visual
 Inherited: no
 Applies to: [=transformable elements=]
 Percentages: Refer to the size of containing block
-Computed value: The ''offset-position/auto'' keyword or a computed <>
+Computed value: The ''offset-position/normal'' or ''offset-position/auto'' keywords, or a computed <>
 Animation type: by computed value
 
 
 Specifies the offset starting position
-that is used by some of the <> functions,
-generally as a starting or "central" point.
-
-Issue: Currently, ''circle()'' and ''ellipse()'' [=offset paths=]
-use this position as their center,
-if the center position is omitted from their arguments.
-This is not an initial position, obviously.
-Whether this is desired is being discussed in
-Issue 504.
+that is used by the <> functions
+if they don't specify their own starting position.
 
 Values are defined as follows:
 
 
+    : normal
+    ::
+        The element does not have an [=offset starting position=].
+
     : auto
     ::
         The [=offset starting position=] is the top-left corner of the box.
 
+        Note: This is the top-left corner of the element's own box,
+        not that of its [=containing block=]!
+        It's completely different from specifiying ''top left''.
+        It's meant, for example,
+        to allow a ''path()'' to start relative
+        to the element's own position.
+
     : <>
     ::
         The [=offset starting position=] is the result of using the <>