CSS Route Matching

1. Conditional rules for navigation queries

1.1. Navigation queries: the @navigation rule

The @navigation rule is a conditional group rule whose condition tests characteristics of the current URL or of the state of navigation between two URLs. These queries are called navigation queries.

Authors can use it to:

• write style sheets that apply to multiple pages but behave somewhat differently between those pages,

• write style sheets that apply to single page applications that change their URL over time, so that style changes when the URL changes, and

• write style sheets that declaratively start view transitions (or make other appropriate style changes) in response to navigations.

The syntax of the condition in the @navigation rule is similar to that defined for <supports-condition> in [CSS-CONDITIONAL-3]. 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.

The syntax of the @navigation rule is:

@navigation <navigation-condition> {
  <rule-list>
}

with <navigation-condition> defined as:

<navigation-condition> = not <navigation-in-parens>
                     | <navigation-in-parens> [ and <navigation-in-parens> ]*
                     | <navigation-in-parens> [ or <navigation-in-parens> ]*
<navigation-in-parens> = ( <navigation-condition> ) | ( <navigation-test> ) | <general-enclosed>
<navigation-test> = <navigation-location> | <navigation-keyword> : <navigation-location>
<navigation-keyword> = at | from | to
<navigation-location> = <urlpattern()>

The above grammar is purposely very loose for forwards-compatibility reasons, since the <general-enclosed> production allows for substantial future extensibility. Any @navigation rule that does not parse according to the grammar above (that is, a rule that does not match this loose grammar which includes the <general-enclosed> production) is invalid. Style sheets must not use such a rule and processors must ignore such a rule (including all of its contents).

Many of these grammar terms are associated with a boolean result, as follows:

<navigation-condition>

not <navigation-in-parens>

The result is the negation of the <navigation-in-parens> term.

<navigation-in-parens> [ and <navigation-in-parens> ]*

The result is true if all of the <navigation-in-parens> child terms are true, and false otherwise.

<navigation-in-parens> [ or <navigation-in-parens> ]*

The result is false if all of the <navigation-in-parens> child terms are false, and true otherwise.

<navigation-in-parens>

The result is the result of the child subexpression.

<navigation-test>

<navigation-location>

at: <navigation-location>

The result is true if the document’s URL matches the navigation location URL pattern of <navigation-location>.

from: <navigation-location>

The result is true if the document’s navigation API of the document is non-null, and either:

• its transition is non-null, its from entry’s url is non-null and matches the navigation location URL pattern of <navigation-location>.

• its activation is non-null, the document’s has been revealed is false or was false at the start of the current task, and the activation’s from’s url’s is non-null and matches the navigation location URL pattern of <navigation-location>.

to: <navigation-location>

The result is true if the document’s navigation API of the document is non-null, and either:

• its ongoing navigate event is non-null, and its destination’s url matches the navigation location URL pattern of <navigation-location>.

  This assumes that the ongoing navigate event and the transition have the same lifetime, but this isn’t really true if the event is intercepted. After whatwg/html#11690 / whatwg/html#11692. we could probably define this more like "from" above. But which lifetime is the one we want?

• its activation is non-null, the document’s has been revealed is false or was false at the start of the current task, and the activation’s entry’s url’s is non-null and matches the navigation location URL pattern of <navigation-location>.

TODO: Update this definition to handle redirects better. In particular, we’d like the to: URL to change at only a single time, from the original URL of the navigation to the final one. There is already a well-defined definition and processing model that we can depend on.

The above definitions of from and to apparently don’t work right if you start a same-document navigation (e.g., with pushState) in the middle of a cross-document navigation.

Improve integration with has been revealed rather than monkeypatching it.

<general-enclosed>

The result is false.

Authors must not use <general-enclosed> in their stylesheets. It exists only for future-compatibility, so that new syntax additions do not invalidate too much of a <navigation-condition> in older user agents.

The navigation location URL pattern of a <navigation-location> depends on the type of <navigation-location>:

<urlpattern()>

The URL pattern represented by the function; see create a URL pattern for urlpattern().

There is currently only one type of <navigation-location> but we should consider adding another, which would be just a name that references a name defined in a routemap. See the route matching explainer for details.

A document’s navigation API is the result of the following steps on document:

1. Let window be the Window whose associated Document is document, or null if there is no such Window.

2. If window is null, return null.

3. Return window’s navigation API.

The condition of the @navigation rule is the result of the <navigation-condition> in its prelude.

1.2. The navigation() function for @when

This specification defines an additional function for the @when rule:

navigation() = navigation( <navigation-condition> )

The navigation() function is associated with the boolean result that its contained condition is associated with.

1.3. The navigation() function for if()

This specification defines an additional function for the if() function’s <if-test> production:

navigation() = navigation( <navigation-condition> )

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.

2. Pseudo-classes for navigation-related links

TODO: To be written.

3. The urlpattern() function

The urlpattern() function represents a URL pattern, which can be used to match URLs.

<urlpattern()> = urlpattern( <string> )

This function represents a URL pattern that can be created using the steps of the create a URL pattern for urlpattern() algorithm:

1. Let arg be the <string> argument to the urlpattern() function.

2. Let baseURL be the style resource base URL of the rule or declaration block containing the urlpattern() function.

   Do we want this to be the base URL all the time? For use of urlpattern() in @navigation, it’s likely more useful for the base URL to be the document URL rather than the style sheet URL. However, it would be very awkward for urlpattern() to be inconsistent with url().

   Should we allow the base URL of urlpattern() to be defined by the consumer? Should we introduce document-urlpattern()? Should we do something similar to CSS Images 3 § 2.1.1 Ambiguous Reference-or-Image URLs (see w3c/csswg-drafts issue #383)?

   Also see other proposed uses of URLPattern in CSS in w3c/csswg-drafts issue #10975, for :local-link.

3. Return the result of create a URL pattern given arg, baseURL, and an empty map.

NOTE: This function requires that its argument is quoted. This differs from the url() function, which allows its argument to be quoted or unquoted.

To serialize a urlpattern() function f, serialize a function f, using serialize a string on the single argument to serialize f’s contents.

NOTE: This is defined this way because URLPattern intentionally does not provide a serialization.