[css-position-3] Rewrite box offsets section.

Author: fantasai

css-position-3/Overview.bs

@@ -747,288 +747,114 @@ Fixed positioning</h3>
 
 <!-- End section: Choosing a positioning scheme: 'position' property -->
 
-<h2 id="box-offsets-trbl">
-Box offsets: 'top', 'right', 'bottom', 'left'</h2>
+<h2 id="coords">
+Positioning Coordinates</h2>
 
-	An element is said to be <a>positioned</a>
-	if its 'position' property has a value other than ''static''.
-	Positioned elements generate positioned boxes,
-	and may be laid out according
-	to the following four physical properties:
+	The precise location of a [=positioned box=] is controlled by
+	the <dfn>inset properties</dfn>:
+	the [=physical=] [=inset properties=] 'top', 'right', 'bottom', 'left';
+	the [=flow-relative=] [=inset properties=] 'inset-block-start', 'inset-inline-start', 'inset-block-end', and 'inset-inline-end';
+	and their [=shorthands=], 'inset-block', 'inset-inline', and 'inset'.
 
-	<pre class="propdef">
-	Name: top
-	Value: auto | <<length-percentage>>
-	Initial: auto
-	Applies to: positioned elements
-	Inherited: no
-	Animation type: length or percentage
-	Percentages: refer to height of <a>containing block</a>
-	Computed value: the keyword ''top/auto'' or a computed <<length-percentage>> value
-	Animation type: by computed value type
-	</pre>
-
-	This property specifies how far an absolutely positioned box’s top margin edge
-	is offset below the top edge of the box’s <a>containing block</a>.
-
-	For relatively positioned boxes,
-	the offset is with respect to the top edge of the box itself
-	(i.e., the box is given a position in the <a>normal flow</a>,
-	and then offset from that position according to this property).
-
-	For sticky positioned boxes,
-	the value is used to compute the <a>sticky-constraint rectangle</a>
-	as described in Sticky positioning.
-
-	For absolutely positioned elements
-	whose <a>containing block</a> is established by a block-level element,
-	this property is an offset from the padding edge of that element.
-
-	<pre class="propdef">
-	Name: right
-	Value: auto | <<length-percentage>>
-	Initial: auto
-	Applies to: positioned elements
-	Inherited: no
-	Animation type: length or percentage
-	Percentages: refer to height of <a>containing block</a>
-	Computed value: the keyword ''right/auto'' or a computed <<length-percentage>> value
-	Animation type: by computed value type
-	</pre>
-
-	Similar to 'top', but specifies how far a box’s right margin edge is offset
-	to the left of the right edge of the box’s <a>containing block</a>.
-
-	For relatively positioned boxes,
-	the offset is with respect to the right edge of the box itself
-	(i.e., the box is given a position in the <a>normal flow</a>,
-	and then offset from that position according to this property).
-
-	For sticky positioned boxes,
-	the value is used to compute the <a>sticky-constraint rectangle</a>
-	as described in Sticky positioning.
-
-	For absolutely positioned elements
-	whose <a>containing block</a> is based on a block-level element,
-	this property is an offset from the padding edge of that element.
-
-	<pre class="propdef">
-	Name: bottom
-	Value: auto | <<length-percentage>>
-	Initial: auto
-	Applies to: positioned elements
-	Inherited: no
-	Animation type: length or percentage
-	Percentages: refer to height of <a>containing block</a>
-	Computed value: the keyword ''bottom/auto'' or a computed <<length-percentage>> value
-	Animation type: by computed value type
-	</pre>
+	The interpretation of these specified coordinates varies by [=positioning scheme=]:
 
-	Similar to 'top', but specifies how far a box’s bottom margin edge is offset
-	above the bottom edge of the box’s <a>containing block</a>.
+	* for [=absolute positioning=], the [=inset properties=] represent
+		insets from the containing block.
+	* for [=relative positioning=], the [=inset properties=] represent
+		insets from the box’s original margin edge.
+	* for [=sticky positioning=], the [=inset properties=] represent
+		insets from the [=scrollport=] edge.
 
-	For relatively positioned boxes,
-	the offset is with respect to the bottom edge	of the box itself
-	(i.e., the box is given a position in the <a>normal flow</a>,
-	and then offset from that position according to this property).
-
-	For sticky positioned boxes,
-	the value is used to compute the <a>sticky-constraint rectangle</a>
-	as described in Sticky positioning.
-
-	For absolutely positioned elements
-	whose <a>containing block</a> is based on a block-level element,
-	this property is an offset from the padding edge of that element.
+<h3 id="insets">
+Box Insets: the 'top', 'right', 'bottom', 'left', 'inset-block-start', 'inset-inline-start', 'inset-block-end', and 'inset-inline-end' properties </h3>
 
 	<pre class="propdef">
-	Name: left
+	Name: top, right, bottom, left, inset-block-start, inset-inline-start, inset-block-end, inset-inline-end
 	Value: auto | <<length-percentage>>
 	Initial: auto
 	Applies to: positioned elements
 	Inherited: no
-	Animation type: length or percentage
-	Percentages: refer to height of <a>containing block</a>
-	Computed value: the keyword ''left/auto'' or a computed <<length-percentage>> value
+	Percentages: refer to size of <a>containing block</a>; see prose
+	Computed value: the keyword ''top/auto'' or a computed <<length-percentage>> value
 	Animation type: by computed value type
 	</pre>
 
-	Similar to 'top', but specifies how far a box’s left margin edge is offset
-	to the right of the left edge of the box’s <a>containing block</a>.
-
-	For relatively positioned boxes,
-	the offset is with respect to the left edge of the box itself
-	(i.e., the box is given a position in the <a>normal flow</a>,
-	and then offset from that position according to this property).
-
-	For sticky positioned boxes,
-	the value is used to compute the <a>sticky-constraint rectangle</a>
-	as described in Sticky positioning.
-
-	For absolutely positioned elements
-	whose <a>containing block</a> is based on a block-level element,
-	this property is an offset from the padding edge of that element.
-
-	The values for the four properties have the following meanings:
+	These [=inset properties=] represent an inward “inset”
+	on the corresponding side of the box
+	(with respect to the box’s own [=writing mode=];
+	see [[!CSS-WRITING-MODES-3#abstract-box]]).
+	For example, 'top' represents a downward inset of the top edge.
+	The [=physical=] and [=flow-relative=] properties
+	interact as defined in [[!CSS-LOGICAL-1]].
+	Values have the following meanings:
 
-	<dl dfn-for="top,right,bottom,left, offset-start, offset-end, offset-before, offset-after" dfn-type="value">
+	<dl dfn-for="top,right,bottom,left, inset-block-start,inset-inline-start,inset-block-end,inset-inline-end inset-block,inset-inline,inset" dfn-type="value">
 		<dt><dfn>&lt;length></dfn>
 		<dd>
-			The offset is a fixed distance from the reference edge.
+			The inset is a fixed distance from the reference edge.
 			Negative values are allowed.
 
 		<dt><dfn>&lt;percentage></dfn>
 		<dd>
-			The offset is a percentage of the <a>containing block’s</a>
-			width (for 'left' or 'right') or height (for 'top' and 'bottom').
-			For sticky positioned elements,
-			the offset is a percentage of the flow root's
-			width (for 'left' or 'right') or height (for 'top' or 'bottom').
+			The inset is a percentage
+			relative to the <a>containing block</a>’s size
+			in the corresponding axis
+			(e.g. width for 'left' or 'right', height for 'top' and 'bottom').
+			For [=sticky positioned=] boxes,
+			the inset is instead 
+			relative to the relevant [=scrollport=]’s size.
 			Negative values are allowed.
 
 		<dt><dfn>auto</dfn></dt>
 		<dd>
-			For non-replaced elements,
-			the effect of this value depends on which of related properties
-			have the value ''top/auto'' as well.
-			See the sections on the 'width' and 'height' of absolutely positioned, non-replaced elements for details.
-			For replaced elements,
-			the effect of this value depends only on the intrinsic dimensions of the replaced content.
-			See the sections on the 'width' and 'height' of absolutely positioned, replaced elements for details.
+			Represents an unconstrained inset;
+			the exact meaning depends on the [=positioning scheme=].
 	</dl>
 
-	<p class="note">
-		Note, for fixed positioned elements,
-		using large values or negative values can easily move elements outside the <a>viewport</a>
-		and make the contents unreachable through scrolling or other means.
-		Authors should be aware that fixed position elements
-		are always relative to the <span>initial containing block</span>.
-	</p>
-<!-- End section: Box offsets: 'top', 'right', 'bottom', 'left'	-->
-
-<h3 id="logical-box-offsets-beaso">
-Logical Box Insets: 'inset-before', 'inset-end', 'inset-after' and 'inset-start'</h3>
-
-	Issue: See [[!CSS-LOGICAL-1]]; this section is not up-to-date.
-
-	Logical offset properties allow for insetting positioned boxes
-	based on the 'writing-mode' and 'direction' properties.
-	When both the physical property
-	and equivalent logical property (based on 'writing-mode' and 'direction')
-	are specified
-	the physical property computes to the computed value of the corresponding logical property.
+	Note: For [=fixed positioned=] elements,
+	using large values or negative values
+	can easily move elements outside the <a>viewport</a>
+	and make the contents unreachable through scrolling or other means.
 
-	Positioned elements generate positioned boxes,
-	and may be laid out according to the following four logical properties
-	taking into account the 'writing-mode' and 'direction' of the <a>containing block</a>:
+<h3 id="inset-shorthands">
+Box Insets Shorthands: the 'inset-block', 'inset-inline', and 'inset' properties</h3>
 
 	<pre class="propdef">
-		Name: inset-before, inset-after, inset-start, inset-end
-		Value: auto | <<length-percentage>>
-		Initial: auto
-		Applies to: positioned elements
-		Inherited: no
-		Animation type: length or percentage
-		Percentages: refer to height of <a>containing block</a>
-		Computed value: the keyword ''inset-before/auto'' or a computed <<length-percentage>> value
-		Animation type: by computed value type
+	Name: inset-block, inset-inline
+	Value: <'top'>{1,2}
+	Initial: auto
+	Applies to: positioned elements
+	Inherited: no
+	Percentages: see individual properties
+	Computed value: see individual properties
+	Animation type: by computed value type
 	</pre>
 
-	For an absolutely positioned box
-	this property specifies how far the corresponding margin edge is offset
-	from the corresponding physical reference edge of the box’s <a>containing block</a>.
-
-	The particular physical reference edge that is used when offsetting
-	is based on the 'writing-mode' and 'direction' properties.
-
-	The combination of the 'writing-mode' and 'direction' properties
-	determines the appropriate physical reference edge for offsetting.
+	The 'inset-block' and 'inset-inline' properties are [=shorthand properties=]
+	for setting 'inset-block-start' + 'inset-block-end'
+	or 'inset-inline-start' + 'inset-inline-end',
+	respectively,
+	in a single declaration.
+	The first component value sets the start side,
+	the second sets the end;
+	if omitted, the second value defaults to the first.
 
-	The table below shows logical offset properties
-	(per 'writing-mode' and 'direction')
-	and the physical reference edge from which the offset will occur.
-
-	<figure>
-		<table id="logical-physical-relations" class="lpr">
-			<thead>
-				<tr>
-					<th colspan="2" rowspan="2"></th>
-					<td colspan="6">'writing-mode' / 'direction'
-				</tr>
-				<tr>
-					<td>horizontal-tb / ltr
-					<td>horizontal-tb / rtl
-					<td>vertical-rl / ltr
-					<td>vertical-rl / rtl
-					<td>vertical-lr / ltr
-					<td>vertical-lr / rtl
-				</tr>
-			</thead>
-			<tbody>
-				<tr>
-					<td rowspan="4"><div>Edge</div>
-					<td>top
-					<td>inset-before
-					<td>inset-before
-					<td>inset-start
-					<td>inset-end
-					<td>inset-start
-					<td>inset-end
-				</tr>
-				<tr>
-					<td>right
-					<td>inset-end
-					<td>inset-start
-					<td>inset-before
-					<td>inset-before
-					<td>inset-after
-					<td>inset-after
-				</tr>
-				<tr>
-					<td>bottom
-					<td>inset-after
-					<td>inset-after
-					<td>inset-end
-					<td>inset-start
-					<td>inset-end
-					<td>inset-start
-				</tr>
-				<tr>
-					<td>left
-					<td>inset-start
-					<td>inset-end
-					<td>inset-after
-					<td>inset-after
-					<td>inset-before
-					<td>inset-before
-				</tr>
-			</tbody>
-		</table>
-		<figcaption>
-			Relationship of physical inset edges and the logical properties per
-			'writing-mode' and 'direction'.
-		</figcaption>
-	</figure>
-
-	Issue: The logical property definitions should move to the Logical Properties module.
-
-	For relatively positioned boxes,
-	the inset is with respect to
-	the property’s corresponding physical reference edge of the box itself
-	(i.e., the box is given a position in the <a>normal flow</a>,
-	and then offset from that position according to the property).
-
-	Issue: This needs to be defined for sticky positioning.
-
-	For absolutely positioned elements
-	whose <a>containing block</a> is based on a block-level element,
-	this property is an inset from the corresponding padding edge of that element.
+	<pre class="propdef">
+	Name: inset
+	Value: <'top'>{1,4}
+	Initial: auto
+	Applies to: positioned elements
+	Inherited: no
+	Percentages: see individual properties
+	Computed value: see individual properties
+	Animation type: by computed value type
+	</pre>
 
-	Note: For fixed positioned elements,
-	using large values or negative values
-	can easily move elements outside the <a>viewport</a>
-	and make the contents unreachable through scrolling or other means.
-	Authors should be aware that fixed position elements
-	are always relative to the <span>initial containing block</span>.
+	The 'inset' property is a [=shorthand property=]
+	that sets all of the [=inset properties=]
+	in a single declaration,
+	assigning values to the longhands representing each side
+	exactly as the 'margin' property does for its longhands.
 
 <h2 id="size-and-position-details">
 Sizing and positioning details</h2>