[css-shapes-1] Add xywh() and redefine rect() for <basic-shape> purposes. w3c#7058

Author: tabatkins

css-shapes-1/Overview.bs

@@ -337,44 +337,103 @@ Supported Shapes</h3>
 	and are defined here using the
 	<a href="https://www.w3.org/TR/css3-values/#value-defs">Value Definition Syntax</a>.
 
-	<dl>
+	<dl dfn-for="<basic-shape>">
 		<dt><dfn>inset()</dfn> =
 			inset( <<length-percentage>>{1,4} [ round <<'border-radius'>> ]? )
 		</dt>
 		<dd>
-			Defines an inset rectangle.
-			<ul>
-				<li>
-					When all of the first four arguments
-					are supplied they represent the
-					<strong>top, right, bottom</strong> and
-					<strong>left</strong> offsets
-					from the <a>reference box</a> inward
-					that define the positions
-					of the edges
-					of the inset rectangle.
-					These arguments follow the syntax
-					of the 'margin' shorthand,
-					that let you set all four insets
-					with one, two or four values.
-				</li>
-				<li>
-					The optional <<'border-radius'>> argument(s)
-					define rounded corners for the inset rectangle
-					using the 'border-radius' shorthand syntax.
-				</li>
-			</ul>
+			Defines an inset rectangle
+			via insets from each edge of the [=reference box=].
+
+			If less than four <<length-percentage>> values are provided,
+			the omitted values default in the same way as the 'margin' shorthand:
+			an omitted second or third value defaults to the first,
+			and an omitted fourth value defaults to the second.
+
+			The four <<length-percentage>>s
+			define the position of the top, right, bottom, and left edges of a rectangle,
+			respectively,
+			as insets from the corresponding edges of the [=reference box=].
 
 			A pair of insets in either dimension
 			that add up to more than the used dimension
 			(such as left and right insets of 75% apiece)
 			use the [[css-backgrounds-3#corner-overlap]] rules 
-			to proportionally reduce the inset effect to 100%. 
-			This will result in a shape edge positioned 
-			within the reference box 
-			(at 50%, in the case of two 75% inset values). 
+			to proportionally reduce the inset effect to 100%.
+
+			<div class=example>
+				For example, specifying ''inset(75% 0 50% 0)''
+				has the top+bottom edges summing to 125%
+				of the [=reference box's=] height.
+				They're proportionaly reduced to sum to 100%,
+				identical to specifying ''inset(60% 0 40% 0)''.
+			</div>
+
+			The optional <<'border-radius'>> argument(s)
+			define rounded corners for the rectangle
+			using the 'border-radius' shorthand syntax.
+
+		<dt><dfn>xywh()</dfn> =
+			xywh( <<length-percentage>>{2} <<length-percentage [0, ∞]>>{2} [ round <<'border-radius'>> ]? )
+		<dd>
+			Defines a rectangle
+			via offsets from the top and left edge of the [=reference box=],
+			and a specified width and height.
+
+			The four <<length-percentages>> define,
+			respectively,
+			the inset from the left edge of the [=reference box=],
+			the inset from the top edge of the [=reference box=],
+			the width of the rectangle,
+			and the height of the rectangle.
+
+			Note: This syntax is inspired by the <{svg/viewBox}> attribute from SVG.
+
+			The optional <<'border-radius'>> argument(s)
+			define rounded corners for the inset rectangle
+			using the 'border-radius' shorthand syntax.
+
+		<dt><dfn>rect()</dfn> =
+			rect( [ <<length-percentage>> | auto ]{4} [ round <<'border-radius'>> ]? )
+		<dd>
+			Defines a rectangle
+			via insets from the top and left edges of the [=reference box=].
+
+			The four <<length-percentage>>s
+			define the position of the top, right, bottom, and left edges of a rectangle,
+			respectively,
+			as insets from the top edge of the [=reference box=]
+			(for the first and third values)
+			or the left edge of the [=reference box=]
+			(for the second and fourth values).
+
+			An <css>auto</css> value makes the edge of the box
+			coincide with the corresponding edge of the [=reference box=]:
+			it's equivalent to ''0%''
+			as the first (top) or fourth (left) value,
+			and equivalent to ''100%''
+			as the second (right) or third (bottom) value.
+
+			The second (right) and third (bottom) values are floored
+			by the fourth (left) and second (top) values, respectively.
+
+			<div class='example'>
+				For example, specifying ''rect(10px 0 0 20px)''
+				would place the bottom edge higher than the top edge,
+				and the right edge further left than the left edge,
+				so both are corrected to not cross over the other edge,
+				identical to specifying ''rect(10px 20px 10px 20px)''.
+			</div>
+
+			Note: This syntax is similar,
+			but not quite identical,
+			to the legacy ''rect()'' function
+			used solely by the 'clip' property.
+
+			The optional <<'border-radius'>> argument(s)
+			define rounded corners for the rectangle
+			using the 'border-radius' shorthand syntax.)
 
-		</dd>
 		<dt><dfn>circle()</dfn> =
 			circle( <<shape-radius>>? [ at <<position>> ]? )
 		</dt>
@@ -516,6 +575,13 @@ Supported Shapes</h3>
 			</ul>
 	</dl>
 
+	Additionally, the three rectangular shape functions
+	are grouped into a production for convenience:
+
+	<pre class=prod>
+	<dfn>&lt;basic-shape-rect></dfn> = <<inset()>> | <<rect()>> | <<xywh()>>
+	</pre>
+
 <h3 id='basic-shape-computed-values'>
 Computed Values of Basic Shapes</h3>
 
@@ -529,7 +595,8 @@ Computed Values of Basic Shapes</h3>
 			A <<position>> value in ''circle()'' or ''ellipse()'' is computed as a pair of offsets (horizontal then vertical) from the top left origin, each given as a <<length-percentage>>.
 		</li>
 		<li>
-			A <<'border-radius'>> value in ''inset()'' is computed as an expanded list of all eight <<length-percentage>> values.
+			A <<'border-radius'>> value in a <<basic-shape-rect>> function
+			is computed as an expanded list of all eight <<length-percentage>> values.
 		</li>
 	</ul>