[css-anchor-position] Rewrite intro, add an example.

Author: tabatkins

css-anchor-position-1/Overview.bs

@@ -42,19 +42,54 @@ spec:css-cascade-5; type:dfn; text:property
 Introduction {#intro}
 =====================
 
-While CSS generally determines the position and size of elements
-according to their parents or other ancestors,
-[=absolutely positioned=] elements barely participate in their ancestors' layout.
-Instead, they're sized and positioned explicitly
-by the [=inset properties=] and [=box alignment properties=],
-only referencing the final size and position of their [=containing block=].
-This provides extreme flexibility,
-allowing elements to be positioned more or less arbitrarily,
-including over the top of other elements
-in ways that the layout methods don't otherwise allow,
-but in return it's not very expressive--
-the element cannot easily express its size and position
-in terms of other elements on the page.
+CSS [=absolute positioning=] allows authors
+to place elements anywhere on the page,
+without regard to the layout of other elements
+besides their containing block.
+This flexibility can be very useful,
+but also very limiting--
+often you want to position relative to <em>some</em> other element.
+<dfn export>Anchor positioning</dfn> allows authors to achieve this,
+"anchoring" an [=absolutely-positioned=] element
+to one or more other elements on the page,
+while also allowing them to try several possible positions
+to find the "best" one that avoids overlap/overflow.
+
+For example, an author might want to position a tooltip
+centered and above the targeted element,
+unless that would place the tooltip offscreen,
+in which case it should be below the targeted element.
+This can be done with the following CSS:
+
+<div class=example>
+	<pre class=lang-css>
+	.anchor {
+		anchor-name: --tooltip;
+	}
+	.tooltip {
+		/* Fixpos means we don't need to worry about
+		   containing block relationships;
+		   the tooltip can live anywhere in the DOM. */
+		position: fixed;
+
+		/* Align the tooltip's bottom to the top of the anchor,
+		   but automatically swap if this overflows the window
+		   to the tooltip's top aligns to the anchor's bottom
+		   instead. */
+		bottom: anchor(--tooltip auto);
+
+		/* Set up a 300px-wide area, centered on the anchor.
+		   If centering would put part of it off-screen,
+		   instead clamp it to remain on-screen. */
+		left: clamp(0px, anchor(--tooltip center) - 150px, 100% - 300px);
+		right: clamp(0px, anchor(--tooltip center) - 150px, 100% - 300px);
+		max-width: 300px;
+
+		/* Center the tooltip in that area. */
+		justify-self: center;
+	}
+	</pre>
+</div>
 
 Anchoring {#anchoring}
 ==================================