[css-anchor-1] Define anchor(auto) for auto-flipping. w3c#7757

Author: tabatkins

css-anchor-1/Overview.bs

@@ -94,8 +94,8 @@ The ''anchor()'' function resolves to a <<length>>.
 
 <pre class=prod>
 &lt;anchor()> = anchor( <<anchor-element>>? <<anchor-side>>, <<length-percentage>>? )
-<dfn><<anchor-element>></dfn> = auto | <<dashed-ident>> | implicit | popover
-<dfn><<anchor-side>></dfn> = top | left | right | bottom
+<dfn><<anchor-element>></dfn> = <<dashed-ident>> | implicit | popover
+<dfn><<anchor-side>></dfn> = auto | top | left | right | bottom
 			  | start | end | self-start | self-end
 			  | <<percentage>> | center
 </pre>
@@ -105,15 +105,11 @@ The ''anchor()'' function has three arguments:
 * the <<anchor-element>> value
 	specifies how to find the [=anchor element=]
 	it will be drawing positioning information from.
-	If omitted, it behaves as ''auto''.
+	If omitted, it behaves as the element's [=default anchor specifier=].
 
 	Its possible values are:
 
 	<dl dfn-type=value dfn-for="anchor()">
-		: <dfn>auto</dfn>
-		:: Uses the [=default anchor specifier=],
-			as specified by 'anchor-default'.
-
 		: <dfn><<dashed-ident>></dfn>
 		:: Specifies the [=anchor name=] it will look for.
 			This name is a [=tree-scoped reference=].
@@ -135,6 +131,10 @@ The ''anchor()'' function has three arguments:
 	refers to the position of the corresponding side
 	of the [=target anchor element=].
 
+	The <dfn value for=anchor()>auto</dfn> keyword
+	indicates [=automatic anchor positioning=].
+	See [[#auto-anchor]] for details.
+
 	The physical <<anchor-side>> keywords
 	(<dfn value for=anchor()>left</dfn>,
 	<dfn value for=anchor()>right</dfn>,
@@ -265,6 +265,79 @@ as if by an additional ''translate()'' transform.
 	which input is being referred to.
 </div>
 
+<!-- Big Text: auto -->
+
+<h4 id=anchor-auto>
+Automatic Anchor Positioning</h4>
+
+A positioned element can use <dfn>automatic anchor positioning</dfn>
+by specifying ''anchor()/auto'' as its <<anchor-side>> value,
+causing the element to automatically stick "next to" the [=anchor element=]
+in the most obvious way,
+and flip to the other side if necessary.
+
+[=Automatic anchor positioning=] is only valid
+if the opposite [=inset property=] is ''top/auto''.
+(For example, if an element had ''top: anchor(auto);'',
+it would have to also have ''bottom: auto;''.)
+If this is not the case,
+the ''anchor()'' function represents an [=invalid anchor query=].
+
+When used in a given [=inset property=],
+the ''anchor()/auto'' <<anchor-side>>
+behaves as the opposite side of the property it's used in.
+That is, when used in ''top: anchor(auto);'',
+it's equivalent to ''top: anchor(bottom);'';
+when used in ''bottom: anchor(auto);'',
+it's equivalent to ''bottom: anchor(top);'';
+etc.
+
+Additionally,
+it automatically adds one entry
+to the beginning of the element's [=position fallback list=]
+(preceding any entries added by 'position-fallback'),
+specifying the [=inset property=] the function is used in
+as ''top/auto'',
+and the opposite property as this property's value.
+
+<div class=example>
+	For example, the following code using [=automatic anchor positioning=]:
+
+	<pre highlight=css>
+	.foo {
+		position: absolute;
+		top: calc(.5em + anchor(--foo auto));
+	}
+	</pre>
+
+	is equivalent to the following more verbose and explicit code:
+
+	<pre highlight=css>
+	.foo {
+		position: absolute;
+		top: calc(.5em + anchor(--foo bottom));
+		position-fallback: --flip;
+	}
+	@position-fallback --flip {
+		@try {
+			top: auto;
+			bottom: calc(.5em + anchor(--foo top));
+		}
+	}
+	</pre>
+</div>
+
+If the element uses [=automatic anchor positioning=] in both axises,
+it instead adds three entries to the [=position fallback list=]:
+one reversing just the block axis,
+one reversing just the inline axis,
+and finally one reversing both axises at once.
+
+''anchor(auto)'' functions specified <em>in</em> a [=position fallback list's=] styles
+do not cause any entries to be added to the list;
+they merely resolve to the appropriate side as normal.
+
+
 <!--
    ███             ██████  ████ ████████ ████████   ███ ███
   ██ ██           ██    ██  ██       ██  ██        ██     ██