[css-navigation-1] Add a bunch of examples. (#13154)

(Also fix an edit I missed adding support for named routes declared by
@route to :link-to().)

Author: dbaron

css-navigation-1/Overview.bs

@@ -132,6 +132,48 @@ Negation, conjunction, and disjunction are all needed
 so that authors can specify the interaction of multiple styles
 in ways that are most intuitive and require the simplest code.
 
+<div class="example">
+
+The ''@navigation'' rule can be used in simple cases
+to define styles that only affect a particular page:
+
+<pre highlight="css">
+@navigation (at: url-pattern("/")) {
+  /* These styles only apply to the site's homepage
+     (including any URL with a search or hash). */
+}
+</pre>
+
+</div>
+
+<div class="example">
+
+The ''@navigation'' rule can also be used to define styles
+that are used when a certain navigation is in progress.
+This is particularly useful for defining
+styles that cause [=view transitions=].
+
+<pre highlight="css">
+@route --search-results-page {
+  pattern: url-pattern("/search-results");
+}
+@route --product-page {
+  pattern: url-pattern("/product/:id");
+}
+
+@navigation ((from: --search-results-page) and
+             (to: --product-page)) or
+            ((from: --product-page) and
+             (to: --search-results-page)) {
+  /* These styles apply when a navigation is in progress
+     between a search results page and a product page (as
+     defined by the @route rules above), in either
+     direction. */
+}
+</pre>
+
+</div>
+
 The syntax of the ''@navigation'' rule is:
 
 <pre class="prod def" nohighlight>
@@ -350,20 +392,93 @@ ISSUE: This should probably have a more formal definition of the function,
 but I can't find the formal definitions of the existing ''if()'' functions
 to model it after.
 
-<h2 id="link-navigation-pseudo-classes">Pseudo-classes for navigation-related links</h2>
+<h2 id="link-navigation-pseudo-classes">Pseudo-class for navigation-related links: '':link-to()''</h2>
 
 This specification defines a new
 <dfn id="link-to-pseudo" selector>'':link-to()''</dfn> functional pseudo-class
 that matches link elements that link to a certain URL.
 
+<div class="example">
+
+A simple example of a ''::link-to()'' selector is this one,
+which matches any links that link to the site's homepage:
+
+<pre highlight=css>
+:link-to(url-pattern("/")) {
+  font-weight: bold;
+}
+</pre>
+
+</div>
+
+<div class="example">
+
+A more interesting example of the ''::link-to()'' pseudo-class
+is this example which creates a view transition between
+a item in a list that contains a link (in this document)
+and the details page for that link (in a different document).
+This transition works even when the navigation is a back/forward navigation
+and even if the user has used a language selector UI
+to change the page into a different language (and thus change the URL).
+The use of the '':link-to()'' pseudo-class ensures that
+the view transition animations from or to the correct item in the list
+by matching the relevant parts of the navigation URL to the link URL.
+
+<pre highlight=css>
+@view-transition {
+  /* allow cross-document view transitions */
+  navigation: auto;
+}
+
+@route --movie-details {
+  /* match URLs like /en/movie/123 which is the English page
+     about a movie with ID 123 */
+  pattern: url-pattern("/:lang/movie/:id");
+}
+
+/* capture the overall area representing the movie, and a
+   sub-area for its poster image */
+
+/* match an element with class movie-container with a child
+   link that links to a movie whose id is the same as the
+   movie we are currently navigating to or from.  (lang can
+   be different, though.)
+
+   Just :link-to(--movie-details) requires that the target
+   of the link match the URL pattern defined by the "@route
+   --movie-details" rule.
+
+   The navigation-param(id) further requires that either the
+   from or the to URL of the current navigation also match
+   the URL pattern represented by the "@route
+   --movie-details" rule, and that that the 'id' named group
+   from that match be the same as the 'id' named group from
+   the match with the link's target.
+   */
+.movie-container:has(> .movie-title:link-to(
+  --movie-details with (navigation-param(id)))) {
+
+  view-transition-name: movie-container;
+
+  > .movie-poster {
+    view-transition-name: movie-poster;
+  }
+
+  /* leave the default cross-fade animation for both image
+     captures */
+}
+</pre>
+
+</div>
+
 The '':link-to()'' pseudo-class takes a single argument, a <<link-condition>>,
 and the pseudo-class matches any element where:
 * the element matches '':any-link''
 * the target of link matches the <<link-condition>>, as defined below.
 
 <pre class="prod def" dfn-type="type" nohighlight>
 <dfn><<link-condition>></dfn> = <<link-condition-base>> [ with <<navigation-param-expression>> ]?
-<dfn><<link-condition-base>></dfn> = <<url-pattern()>>
+<dfn><<link-condition-base>></dfn> = <<navigation-location>>
 <dfn><<navigation-param-expression>></dfn> = ( [ <<navigation-param-and>> |
                                     <<navigation-param-or>> |
                                     <<navigation-param>> ] )
@@ -376,6 +491,9 @@ and the pseudo-class matches any element where:
 <dfn><<navigation-param-function>></dfn> = navigation-param( <<ident>> )
 </pre>
 
+ISSUE: This grammar should be restructured so that
+it doesn't require parentheses around a lone <<navigation-param-function>>.
+
 A <<link-condition>> matches the target of the link when both:
 * the <<link-condition-base>> matches the target of the link, and
 * the <<navigation-param-expression>> matches the target of the link,
@@ -386,6 +504,8 @@ If the <<link-condition-base>> is a <<url-pattern()>>,
 then it represents the URL pattern
 represented by the <<url-pattern()>> function
 (see [=create a URL pattern for url-pattern()=]).
+If it is a <<route-name>>, then it represents the URL pattern
+represented by the ''@route'' rule.
 
 A <<link-condition-base>> matches a URL
 when [=URL pattern/match|match a URL pattern=] is non-null