Title: CSS Route Matching
Status: ED
Work Status: Exploring
Shortname: css-navigation
Level: 1
Group: csswg
ED: https://drafts.csswg.org/css-navigation-1/
!Issue Tracking: w3c/csswg-drafts#12594
Editor: L. David Baron, Google https://www.google.com/, https://dbaron.org/, w3cid 15393
Editor: Noam Rosenthal, Google https://www.google.com/, w3cid 121539
Abstract: This module contains conditional CSS rules for styling conditioned on the current URL
        or conditioned on the status of navigating between particular URLs.

spec:css-values-5; type:function; text:if()

url: https://html.spec.whatwg.org/multipage/nav-history-apis.html#concept-navigationtransition-from
    type: dfn; spec: html; text: from entry;
url: https://html.spec.whatwg.org/multipage/nav-history-apis.html#window-navigation-api
    type: dfn; spec: html; text: navigation API;
url: https://html.spec.whatwg.org/multipage/nav-history-apis.html#ongoing-navigate-event
    type: dfn; spec: html; text: ongoing navigate event;
url: https://html.spec.whatwg.org/multipage/nav-history-apis.html#concept-navigation-transition
    type: dfn; spec: html; text: transition;
url: https://html.spec.whatwg.org/multipage/nav-history-apis.html#navigation-activation
    type: dfn; spec: html; text: activation;
url: https://html.spec.whatwg.org/multipage/browsing-the-web.html#has-been-revealed
    type: dfn; spec: html; text: has been revealed;
url: https://drafts.csswg.org/css-view-transitions-1/#capture-the-image
    type: dfn; spec: css-view-transitions-1; text: capture the image;

Declaring named URL patterns: the ''@route'' rule

The @route rule is an at-rule that associates a name with a [=URL pattern=]. This name can be referenced in ''@navigation'' rules and in '':link-to()'' pseudo-classes. The syntax of the ''@route'' rule is: 
@route <> {
  [ <> | <> ]
}
based on the following definitions: 
<> = ;* <> ;*
<> = pattern : <>
<> = ;* <> [ ;+ <> ]* ;*
<> = <> : <>
<> = protocol | hostname | port | pathname |
                         search | hash | base-url
This associates an author-defined keyword with a URL pattern, so that any URL that matches one of the URL patterns matches the route named by the keyword. The ''@route'' rule can be defined in one of two ways: : with the pattern descriptor :: in this case the URL pattern represented is the one represented by the <> function given as the descriptor's value. : with the other descriptors named by <> :: In this case the URL pattern represented is the result of invoking [=URL pattern/create|create a URL pattern=] given input as {{URLPatternInit}} constructed from the descriptors and their values. Each dictionary member is given the value of the descriptor with the same name, except the baseURL member is given the value of the base-url descriptor. If a base-url descriptor is not given then one is created from the [=style resource base URL=] of the rule. ISSUE: Should this use <>, <>, or <> for the route names? ISSUE: Is there value in being able to provide a list of <> rather than just one? NOTE: The list of allowed init descriptors does not include username or password since they seem unlikely to be useful.
It's possible that this syntax with init descriptors in the ''@route'' rule would make more sense as part of the ''urlpattern()'' function (that is, as an alternate syntax for what goes inside the function). This would also give us the option to remove the braces from the syntax of the ''@route'' rule and make it more like ''@import'' or ''@namespace''. This does remove a potential future extensibility point, but it could also be added back later if we need it.
Either this rule: 
@route --movie-list {
  pattern: url-pattern("/movie-list");
}
or this rule: 
@route --movie-list {
  pathname: "/movie-list";
}
define an ''@route'' rule that associates the name --movie-list with the URL "/movie-list" resolved relative to the style sheet.
NOTE: The bracing syntax also allows for future expansion if needed. NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#12594.

Conditional rules for navigation queries

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 <> 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 ''@navigation'' rule can be used in simple cases to define styles that only affect a particular page: 
@navigation (at: url-pattern("/")) {
  /* These styles only apply to the site's homepage
     (including any URL with a search or hash). */
}
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=]. 
@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) {
  /* These styles apply when a navigation is in progress
     from a search results page to a product page (as
     defined by the @route rules above), but not in the
     reverse direction. */
}

@navigation (between: --search-results-page and --product-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. */
}
The syntax of the ''@navigation'' rule is: 
@navigation <> {
  <>
}
with <> defined as: 
<> = not <>
                     | <> [ and <> ]*
                     | <> [ or <> ]*
<> = ( <> ) | ( <> ) | <>
<> = <> |
                    <> |
                    <>

<> = <> : <>
<> = at | other | from | to
<> = <> | <>
<> = <>

<> =
    between : <> and <>

<> = history : <>
<> = traverse | back | forward | reload
ISSUE: Should we use ''at'' or ''current''? The above grammar is purposely very loose for forwards-compatibility reasons, since the <> 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 <> 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: : <> :: : not <> :: The result is the negation of the <> term. : <> [ and <> ]* :: The result is true if all of the <> child terms are true, and false otherwise. : <> [ or <> ]* :: The result is false if all of the <> child terms are false, and true otherwise. : <> :: The result is the result of the child subexpression. : <> :: : at: <> :: The result is whether the result of [=URL pattern/match|match a URL pattern=] is non-null given urlPattern as the [=navigation location URL pattern=] of <> and input as the document's [=Document/URL=]. : other: <> :: The result is true if the [=current other URL=] other of the document is non-null and [=URL pattern/match|match a URL pattern=] is non-null when given urlPattern as the [=navigation location URL pattern=] of <> and input as other. : from: <> :: The result is true if the [=current from URL=] from of the document is non-null and [=URL pattern/match|match a URL pattern=] is non-null when given urlPattern as the [=navigation location URL pattern=] of <> and input as from. : to: <> :: The result is true if the [=current to URL=] to of the document is non-null and [=URL pattern/match|match a URL pattern=] is non-null when given urlPattern as the [=navigation location URL pattern=] of <> and input as to. : <> :: : between: <> and <> :: The result is true if the [=current from URL=] from of the document is non-null, the [=current to URL=] to of the document is non-null, [=URL pattern/match|match a URL pattern=] is non-null given urlPattern as the [=navigation location URL pattern=] of one of the two <>s and input as from, and [=URL pattern/match|match a URL pattern=] is non-null given urlPattern as the [=navigation location URL pattern=] of the other of the two <>s and input as to. : <> :: : history: traverse :: True if the [=current navigation type=] is {{NavigationType/traverse}}. : history: back :: True if the [=current navigation type=] is {{NavigationType/traverse}} and the [=current navigation delta=] is less than 0. : history: forward :: True if the [=current navigation type=] is {{NavigationType/traverse}} and the [=current navigation delta=] is greater than 0. : history: reload :: True if the [=current navigation type=] is {{NavigationType/reload}}. : <> :: The result is false. Authors must not use <> in their stylesheets. It exists only for future-compatibility, so that new syntax additions do not invalidate too much of a <> in older user agents. The navigation location URL pattern of a <> depends on the type of <>: : <> :: the URL pattern represented by the ''@route'' rule referenced by the name. : <> :: The [=URL pattern=] represented by the function; see [=create a URL pattern for url-pattern()=]. ISSUE: Should it also be possible to reference 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}}. 1. If window is null, return null. 1. Return window's [=navigation API=]. The condition of the ''@navigation'' rule is the result of the <> in its prelude. NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#12594 and w3c/csswg-drafts#8209. This specification defines an additional function for the ''@when'' rule: 
navigation() = navigation( <> )
The ''@when/navigation()'' function is associated with the boolean result that its contained condition is associated with. This specification defines an additional function for the ''if()'' function's <> production: 
navigation() = navigation( <> )
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. This specification defines a new '':link-to()'' functional pseudo-class that matches link elements that link to a certain URL.
A simple example of a '':link-to()'' selector is this one, which matches any links that link to the site's homepage: 
:link-to(url-pattern("/")) {
  font-weight: bold;
}
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. 
@view-transition {
  /* allow cross-document view transitions */
  navigation: auto;
}

@route --movie-details-with-id {
  /* match URLs like /en/movie/123 which is the English page
     about a movie with ID 123.  Be careful to specify the
     language part with a "*" but the ID part with a named
     :id parameter so that matching using the 'match-params'
     keyword (the default) will require equal IDs but allow
     differences of language. */
  pattern: url-pattern("/*/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.)

   This depends on the --movie-details-with-id route
   declaring the ID but not the language with a named
   parameter, and the use of match-params(navigation-other).

   This means that both the of the link and the other URL of
   the current navigation match the URL pattern defined by
   the "@route --movie-details-with-id" rule, and that the
   id named group from both matches be the same.  (However,
   the URLs can be different because the * part of the
   match, containing the language, can be different.)
   */
.movie-container:has(
    > .movie-title:link-to(--movie-details-with-id
                             with match-params(navigation-other))) {

  view-transition-name: movie-container;

  > .movie-poster {
    view-transition-name: movie-poster;
  }

  /* leave the default cross-fade animation for both image
     captures */
}
The '':link-to()'' pseudo-class takes a single argument, a <>, and the pseudo-class matches any element where: * the element matches '':any-link'' * the target of link matches the <>, as defined below. 
<> = <> [ with <> ]?
<> = <>
  // Note: <> is defining three functions
  // with identical syntax.
<> = <>( <> )
<> = match-pattern | match-params | match-url
<> = navigation-other | navigation-current |
                            navigation-from | navigation-to
ISSUE: Should we use ''navigation-at'' or ''navigation-current''? ISSUE: Should the '':link-to()'' variant that has a <> have a different name, such as '':navigating-link()''? A <> matches the target of the link when both: * the <> matches the target of the link, and * either: * a <> is not present, or * the <> matches the target of the link, with the [=URL pattern=] represented by the <> as context A <> represents a [=URL pattern=]. If the <> is a <>, then it represents the URL pattern represented by the <> function (see [=create a URL pattern for url-pattern()=]). If it is a <>, then it represents the URL pattern represented by the ''@route'' rule. A <> matches a URL when [=URL pattern/match|match a URL pattern=] is non-null given urlPattern as the [=URL pattern=] that it represents and input as the given URL. A <> matches the URL linkTarget (with a URL Pattern urlPattern as context) if the following steps return true: 1. Let targetMatchResult be the result of [=URL pattern/match|match a URL pattern=] given urlPattern and linkTarget. 1. If targetMatchResult is null, return false. NOTE: This doesn't really matter because in this case the <> also doesn't match. 1. Let matchType be the <> of the <>. 1. Let matchTarget be the <> argument of the <>. 1. Let navigationURL be: : If matchTarget is ''navigation-other'', :: the current other URL of the document. : Otherwise, if matchTarget is ''navigation-current'', :: the document's [[=Document/URL=]]. : Otherwise, if matchTarget is ''navigation-from'', :: the current from URL of the document. : Otherwise (Assert: matchTarget is ''navigation-to''), :: the current to URL of the document. 1. If navigationURL is null, return false. 1. : If matchType is ''match-pattern'' :: Return true if the result of [=URL pattern/match|match a URL pattern=] given urlPattern and navigationURL is not null; otherwise return false. : If matchType is ''match-params'' :: 1. Let navigationMatchResult be the result of [=URL pattern/match|match a URL pattern=] given navigationURL and urlPattern. 1. If either navigationMatchResult is null, return false. 1. For each property prop of {{URLPatternResult}} that is a {{URLPatternComponentResult}}: 1. If {{URLPatternComponentResult/groups}} of prop of targetMatchResult is not equal to {{URLPatternComponentResult/groups}} of prop of navigationMatchResult, then return false. ISSUE: Need to formally define equality of ordered maps. 1. Return true. : If matchType is ''match-url'' :: Return true if linkTarget equals navigationURL; otherwise return false. NOTE: Some of the design discussion for this feature has been in w3c/csswg-drafts#13163.

Definitions of current navigation state

Both the ''@navigation'' rule and the '':link-to()'' pseudo-class rely on the following definitions of the [=current other URL=], [=current from URL=], and [=current to URL=]. The current from URL of a [=/document=] is a URL or null. It is defined as follows: 1. If the [=document's navigation API=] of the document is non-null and its [=transition=] is non-null, its [=from entry=]'s {{NavigationHistoryEntry/url}}. NOTE: This part is for when the old document in the navigation is still the current document. 1. If the [=document's navigation API=] of the document is non-null, its [=activation=] is non-null, the activation's {{NavigationActivation/from}} is non-null, and the document's [=has been revealed=] is false or was false at the start of the current [=task=], the activation's {{NavigationActivation/from}}'s {{NavigationHistoryEntry/url}}. NOTE: This part is for when the new document in the navigation has become the current document. 1. Otherwise, null. NOTE: The previous two branches can also produce null results. The current to URL of a [=/document=] is a URL or null. It is defined as follows: 1. If the [=document's navigation API=] of the document is non-null and its [=ongoing navigate event=] is non-null: 1. if the {{pageswap}} event has fired since that navigation began, and its {{PageSwapEvent/activation}} was non-null, and that {{PageSwapEvent/activation}}'s {{NavigationActivation/entry}}'s {{NavigationHistoryEntry/url}} is non-null, then that {{NavigationHistoryEntry/url}}. NOTE: This part does expose the result of redirects. NOTE: This part is not relevant to normal page rendering. However, it can be relevant to what is rendered when [=capturing the image=] for a [[css-view-transitions-2#cross-document-view-transitions|cross-document view transition]]. ISSUE: Is the final "non-null" check needed? 1. otherwise, the [=ongoing navigate event=]'s {{NavigateEvent/destination}}'s {{NavigationDestination/url}} NOTE: This part does not expose the result of redirects. ISSUE: 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? NOTE: This part is for when the old document in the navigation is still the current document. 1. If the [=document's navigation API=] of the document is non-null and 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 {{NavigationActivation/entry}}'s {{NavigationHistoryEntry/url}}. NOTE: This part is for when the new document in the navigation has become the current document. ISSUE: Does it make sense to expose this when the activation's {{NavigationActivation/from}} is null, and thus there is no [=current from URL=]? 1. Otherwise, null. NOTE: The previous two branches can also produce null results. ISSUE: The above definitions of from and to apparently don't work right if you start a same-document navigation (e.g., with {{History/pushState}}) in the middle of a cross-document navigation. The current other URL of a [=/document=] is a URL or null. It is defined as follows: 1. ISSUE: Write this! The current navigation type of a [=/document=] is a {{NavigationType}} or null. It is defined as follows: 1. If the [=document's navigation API=] of the document is non-null and its [=transition=] is non-null, the transition's {{NavigationTransition/navigationType}}. NOTE: This part is for when the old document in the navigation is still the current document. 1. If the [=document's navigation API=] of the document is non-null and its [=activation=] is non-null, the document's [=has been revealed=] is false or was false at the start of the current [=task=], the activation's {{NavigationActivation/navigationType}}. NOTE: This part is for when the new document in the navigation has become the current document. 1. Otherwise, null. The current navigation delta of a [=/document=] is a {{NavigationType}} or null. It is defined as follows: 1. If the [=document's navigation API=] of the document is non-null and its [=transition=] is non-null, 1. If the transition's {{NavigationTransition/navigationType}} is not {{NavigationType/traverse}}, null. 1. Otherwise, the transition's {{NavigationTransition/to}}'s {{NavigationDestination/index}} minus the transition's {{NavigationTransition/from}}'s {{NavigationHistoryEntry/index}}. NOTE: This part is for when the old document in the navigation is still the current document. 1. If the [=document's navigation API=] of the document is non-null, its [=activation=] is non-null, the activation's {{NavigationActivation/from}} is non-null, and the document's [=has been revealed=] is false or was false at the start of the current [=task=], 1. If the activation's {{NavigationActivation/navigationType}} is not {{NavigationType/traverse}}, null. 1. Otherwise, the activation's {{NavigationActivation/entry}}'s {{NavigationHistoryEntry/index}} minus the activation's {{NavigationActivation/from}}'s {{NavigationHistoryEntry/index}}. NOTE: This part is for when the new document in the navigation has become the current document. 1. Otherwise, null. ISSUE: Generally improve integration with the HTML spec for these definitions, instead of monkeypatching. This includes the interaction with [=has been revealed=] and the interaction with the {{pageswap}} event, and other things where this section links to non-exported definitions. ISSUE: Generally figure out if these definitions should care about the [=ongoing navigate event=] or the [=transition=].

The ''url-pattern()'' function

The url-pattern() function represents a [=URL pattern=], which can be used to match URLs. 
<> = url-pattern( <> )
This function represents a [=URL pattern=] that can be created using the steps of the create a URL pattern for url-pattern() algorithm: 1. Let arg be the <> argument to the ''url-pattern()'' function. 1. Let baseURL be the [=style resource base URL=] of the rule or declaration block containing the ''url-pattern()'' function.
Do we want this to be the base URL all the time? For use of ''url-pattern()'' 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 ''url-pattern()'' to be inconsistent with ''url()''. Should we allow the base URL of ''url-pattern()'' to be defined by the consumer? Should we introduce document-url-pattern()? Should we do something similar to [[css-images-3#ambiguous-urls]] (see )? Also see other proposed uses of {{URLPattern}} in CSS in , for '':local-link''.
1. Return the result of [=URL pattern/create|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 ''url-pattern()'' 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.

Privacy Considerations

ISSUE: To be written.

Security Considerations

ISSUE: To be written.