Overview.bs

<pre class="metadata">
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: <a href="https://github.com/w3c/csswg-drafts/issues/12594">w3c/csswg-drafts#12594</a>
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.
</pre>

<pre class="link-defaults">
spec:css-values-5; type:function; text:if()
</pre>

<!-- FIXME: TEMPORARILY override non-exported definition -->
<pre class=anchors>
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#navigation-current-entry
    type: dfn; spec: html; text: current entry; for: 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://html.spec.whatwg.org/multipage/browsing-the-web.html#ongoing-navigation
    type: dfn; spec: html; text: ongoing navigation;
url: https://drafts.csswg.org/css-view-transitions-1/#capture-the-image
    type: dfn; spec: css-view-transitions-1; text: capture the image;
</pre>

<h2 id="url-patterns-in-css">Defining URL patterns in CSS</h2>

<h3 id="at-route">Declaring named URL patterns: the ''@route'' rule</h3>

The <dfn at-rule id="at-ruledef-route">@route</dfn> rule
is an at-rule that associates a name with a [=URL pattern=].
This name can be referenced in ''@navigation'' rules
and in '':active-navigation()'' pseudo-classes.

The syntax of the ''@route'' rule is described by the <<route-rule>> production in:

<pre class="prod def" nohighlight>
<dfn><<route-rule>></dfn> = @route <<dashed-ident>> { <<declaration-list>> }
</pre>

This means that the rule accepts a sequence of descriptors
that have the syntax of declarations.
However, in valid style sheets the only descriptors must match
the <<route-descriptor>> production below.
Any other descriptors are ignored.

<pre class="prod def" nohighlight>
<dfn><<route-descriptor>></dfn> = <<pattern-descriptor>> |
                     <<init-descriptor>> |
                     <<base-descriptor>>
<dfn><<pattern-descriptor>></dfn> = pattern : <<url-pattern()>>
<dfn><<init-descriptor>></dfn> = <<init-descriptor-name>> : <<string>>
<dfn><<init-descriptor-name>></dfn> = protocol | hostname | port | pathname |
                         search | hash
<dfn><<base-descriptor>></dfn> = base-url : stylesheet | document | <<url>>
</pre>

If two valid descriptors in a single rule have the same name,
the last one is used and the others are ignored.
If a rule has both a valid <<pattern-descriptor>>
and a valid <<init-descriptor>>
then it is ignored.

This rule 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 <code>pattern</code> descriptor
:: in this case the URL pattern represented is
    the result of invoking
    [=create a URL pattern for url-pattern()=] given
    <var>arg</var> as the argument to the ''url-pattern()'' function
    and <var>baseURLSpecifier</var> as
    the (optional) value of the rule's <<base-descriptor>>.
: with the other descriptors named by <<init-descriptor-name>>
:: In this case the URL pattern represented is the result of invoking
    [=URL pattern/create|create a URL pattern=] given
    <var>input</var> 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 <code>baseURL</code> member is given the result of
    [=create a URL for a base descriptor=]
    given <var>baseURLSpecifier</var> as
    the (optional) value of the rule's <<base-descriptor>>.

ISSUE: Should this use <<dashed-ident>>, <<custom-ident>>, or <<ident>>
for the route names?

ISSUE: Should we use <code>base-url</code> or just <code>base</code> as the descriptor name?

NOTE: The list of allowed init descriptors does not include <code>username</code>
or <code>password</code> since they seem unlikely to be useful.

<div class="issue">
It's possible that this syntax with init descriptors in the ''@route'' rule
would make more sense as part of the ''url-pattern()'' 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.
</div>

<div class="example">
Either this rule:
<pre highlight=css>
@route --movie-list {
  pattern: url-pattern("/movie-list");
}
</pre>
or this rule:
<pre highlight=css>
@route --movie-list {
  pathname: "/movie-list";
}
</pre>
define an ''@route'' rule that associates
the name <code>--movie-list</code>
with the URL <code>"/movie-list"</code> resolved relative to the style sheet.
</div>

NOTE: The bracing syntax also allows for future expansion if needed.

NOTE: Some of the design discussion for this feature has been in
<a href="https://github.com/w3c/csswg-drafts/issues/12594">w3c/csswg-drafts#12594</a>.

<h3 id="url-pattern-function">The ''url-pattern()'' function</h3>

<!--

NOTE: We may eventually want to move this to css-values.

If we do, the definition of "style resource base URL" probably doesn't need to be
exported any more, since it was exported for this definition.

-->

The <dfn export function>url-pattern()</dfn> function represents a [=URL pattern=],
which can be used to match URLs.

<pre class="prod def">
<<url-pattern()>> = url-pattern( <<string>> )
</pre>

This function represents the [=URL pattern=] resulting from
invoking [=create a URL pattern for url-pattern()=] with its string argument.

The steps of the <dfn>create a URL pattern for url-pattern()</dfn> algorithm,
given a string <var>arg</var> and
an optional <var>baseURLSpecifier</var>
which can be ''document'', ''stylesheet'', or a URL, are:

1. Let <var>baseURL</var> be the result of
    [=create a URL for a base descriptor=] given <var>baseURLSpecifier</var>.

1. Return the result of [=URL pattern/create|create a URL pattern=] given
    <var>arg</var>, <var>baseURL</var>, 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.

The <dfn>create a URL for a base descriptor</dfn> algorithm, given
an optional <var>baseURLSpecifier</var>
which can be ''document'', ''stylesheet'', or a URL, is:

<dl class=switch>

: if <var>baseURLSpecifier</var> is not present or is ''stylesheet''
:: the [=style resource base URL=] of
    the rule or declaration block containing the ''url-pattern()'' function.

: if <var>baseURLSpecifier</var> is ''document''
:: the [=document base URL=] of the document

: if <var>baseURLSpecifier</var> is a URL
:: <var>baseURLSpecifier</var>

</dl>

<div class="issue">
Should the default always be ''stylesheet''?
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()''.

Also see other proposed uses of {{URLPattern}} in CSS
in <w3c/csswg-drafts#10975>,
for '':local-link''.
</div>


To <dfn export>serialize a ''url-pattern()'' function</dfn> <var>f</var>,
[=serialize a function=] <var>f</var>,
using [=serialize a string=] on the single argument
to serialize <var>f</var>'s contents.

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

<h3 id="route-value-type">The <<route-location>> value type</h3>

<pre class="prod def" dfn-type="type" nohighlight>
<dfn><<route-location>></dfn> = <<route-name>> | <<url-pattern()>> | <<url>>
<dfn><<route-name>></dfn> = <<dashed-ident>>
</pre>

A <<route-location>> is defined to
<dfn for="route-location">match</dfn> a [=/URL=]-or-null <var>input</var> if <var>input</var> is non-null, and:

<dl class=switch>

: the <<route-location>> is a <<route-name>>
:: [=URL pattern/match|match a URL pattern=] is non-null given
    <var>urlPattern</var> as
    the [=URL pattern=] represented by the ''@route'' rule referenced by the name and
    <var>input</var> as <var>input</var>.

: the <<route-location>> is a <<url-pattern()>>
:: [=URL pattern/match|match a URL pattern=] is non-null given
    <var>urlPattern</var> as
    the [=URL pattern=] represented by the function (see
    [=create a URL pattern for url-pattern()=]) and
    <var>input</var> as <var>input</var>.

: the <<route-location>> is a <<url>>
:: The given [=/URL=] [=url/equals=] <var>input</var>.

</dl>

<h2 id="conditional-navigation-queries">Conditional rules for navigation queries</h2>

<h3 id="at-navigation">Navigation queries: the ''@navigation'' rule</h3>

The <dfn at-rule id="at-ruledef-navigation">@navigation</dfn> 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 <dfn export>navigation queries</dfn>.

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.

<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) {
  /* 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. */
}
</pre>

</div>

The syntax of the ''@navigation'' rule is:

<pre class="prod def" nohighlight>
@navigation <<navigation-condition>> {
  <<rule-list>>
}
</pre>

with <<navigation-condition>> defined as:

<pre class="prod def" dfn-type="type" nohighlight>
<dfn><<navigation-condition>></dfn> = not <<navigation-in-parens>>
                     | <<navigation-in-parens>> [ and <<navigation-in-parens>> ]*
                     | <<navigation-in-parens>> [ or <<navigation-in-parens>> ]*
<dfn><<navigation-in-parens>></dfn> = ( <<navigation-condition>> ) | ( <<navigation-test>> ) | <<general-enclosed>>
<dfn><<navigation-test>></dfn> = <<navigation-location-test>> |
                    <<navigation-location-between-test>> |
                    <<navigation-type-test>> |
                    <<navigation-phase-test>>

<dfn><<navigation-location-test>></dfn> = <<navigation-location-keyword>> : <<route-location>>
<dfn><<navigation-location-keyword>></dfn> = at | with | from | to

<dfn><<navigation-location-between-test>></dfn> =
    between : <<route-location>> and <<route-location>>

<dfn><<navigation-type-test>></dfn> = history : <<navigation-type-keyword>>
<dfn><<navigation-type-keyword>></dfn> = traverse | back | forward | reload

<dfn><<navigation-phase-test>></dfn> = phase : <<navigation-phase-keyword>>
<dfn><<navigation-phase-keyword>></dfn> = loading | ready | committed
</pre>

ISSUE: Should we use ''at''/''with''/''from''/''to'' or ''current''/''other''/''from''/''to''?

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 <strong>must not</strong> use such a rule and
processors <strong>must</strong> 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-location-test>>
::  The result is true if
        the <<route-location>> [=route-location/matches=] [=current navigation URL=] of the document given the <<navigation-relation>>.

: <<navigation-location-between-test>>
::    : between: <<route-location>> and <<route-location>>
    :: The result is true if
        the [=current navigation URL=] <var>from</var> of the document given ''from'' is non-null,
        the [=current navigation URL=] <var>to</var> of the document ''to'' is non-null,
        one of the two <<route-location>>s
        [=route-location/matches=] <var>from</var>,
        and the other of the two <<route-location>>s
        [=route-location/matches=] <var>to</var>.

: <<navigation-type-test>>
::    : history: traverse
    :: True if the [=current navigation type=] is {{NavigationType/traverse}}.
    : history: back
    :: True if the [=current navigation type=] is {{NavigationType/traverse}} and
        the document's [=current navigation state=]'s [=navigation state/new index=] is less than its [=navigation state/old index=].
    : history: forward
    :: True if the [=current navigation type=] is {{NavigationType/traverse}} and
        the document's [=current navigation state=]'s [=navigation state/new index=] is greater than its [=navigation state/old index=].
    : history: reload
    :: True if the [=current navigation type=] is {{NavigationType/reload}}.

: <<navigation-phase-test>>
:: The [=current navigation state=] is not null, and its [=navigation state/phase=] matches the given ''phase'' value.

: <<general-enclosed>>
::
    The result is false.

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

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

NOTE: Some of the design discussion for this feature has been in
<a href="https://github.com/w3c/csswg-drafts/issues/12594">w3c/csswg-drafts#12594</a>
and
<a href="https://github.com/w3c/csswg-drafts/issues/8209">w3c/csswg-drafts#8209</a>.

<h3 id="navigation-when-function">The ''@when/navigation()'' function for ''@when''</h3>

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

<pre class="prod">
<dfn for="@when" function>navigation()</dfn> = navigation( <<navigation-condition>> )
</pre>

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

<h3 id="navigation-if-function">The ''if()/navigation()'' function for ''if()''</h3>

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

<pre class="prod">
<dfn for="if()" function>navigation()</dfn> = navigation( <<navigation-condition>> )
</pre>

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 links</h2>

<h3 id="trigger-link-pseudo-class">The '':trigger-link'' pseudo-class</h3>

This specification defines a new
<dfn id="trigger-link-pseudo" selector>'':trigger-link''</dfn>
that matches link elements that trigger the current navigation.

The '':trigger-link'' pseudo-class matches any element where both:
* the element matches '':any-link''
* the [=current navigation state=] is not null, and element is its [=navigation state/source element=].

Issue: should this apply to forms or submit buttons?

<div class="example">

A simple example of a '':trigger-link'' selector is this one,
which sets the ''view-transition-name'' for an image thumbnail that is a child of the link that triggers the current navigation.


<pre highlight=css>
:trigger-link .thumb {
  view-transition-name: active-image;
}
</pre>

</div>

<h3 id="link-to-pseudo-class">The '':link-to()'' pseudo-class</h3>

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>

The '':link-to()'' pseudo-class takes a single argument, a <<route-location>>,
and the pseudo-class matches any element where both:
* the element matches '':any-link''
* the <<route-location>> [=route-location/matches=] the target of the link

<h3 id="active-navigation-pseudo-class">The '':active-navigation()'' pseudo-class</h3>

This specification defines a new
<dfn id="active-navigation-pseudo" selector>'':active-navigation()''</dfn>
functional pseudo-class
that matches link elements that link to a certain URL
that is related to a navigation that is currently active.

<div class="example">

A an example of the '':active-navigation()'' 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-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 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 the 'with' keyword.

   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:active-navigation(with --movie-details-with-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 '':active-navigation()'' pseudo-class takes a single argument, a <<active-navigation-condition>>,
and the pseudo-class matches any element where:
* the element matches '':any-link''
* the target of the link matches the <<active-navigation-condition>>, as defined below.

<pre class="prod def" dfn-type="type" nohighlight>
<dfn><<active-navigation-condition>></dfn> =
  <<navigation-relation>>? [ <<route-location>> | link-href ]?
<dfn><<navigation-relation>></dfn> = at | with | from | to
</pre>

ISSUE: Should we use ''at''/''with''/''from''/''to'' or
''current''/''other''/''from''/''to''?

An <<active-navigation-condition>> matches the target <var>linkTarget</var> of the link when
the following steps return true:
1. Let <var>navigationURL</var> be
    the [=current navigation URL=] of the document given the <<navigation-relation>> in <<active-navigation-condition>> (default ''with'').

1. If <var>navigationURL</var> is null, return false.
1. If ''link-href'' is present, or a <<route-location>> is not provided:
    1. Return true if <var>linkTarget</var> [=url/equals=] <var>navigationURL</var>; Otherwise false.

1. If a <<route-location>> is present:
    1. Let <var>targetMatchResult</var> be the result of
        [=URL pattern/match|matching a URL pattern=]
        given <var>urlPattern</var> and <var>linkTarget</var>.

    1. Let <var>navigationMatchResult</var> be the result of
         [=URL pattern/match|matching a URL pattern=] given
         <var>urlPattern</var> and <var>navigationURL</var>.

    1. If <var>navigationMatchResult</var> or <var>targetMatchResult</var> is null, return false.

    1. For each property <var>prop</var> of {{URLPatternResult}} that is a
        {{URLPatternComponentResult}}:

        1. If {{URLPatternComponentResult/groups}} of <var>prop</var> of
            <var>targetMatchResult</var> is not equal to
            {{URLPatternComponentResult/groups}} of <var>prop</var> of
            <var>navigationMatchResult</var>,
            then return false.

            ISSUE: Need to formally define equality of ordered maps.

    1. Return true.

NOTE: Some of the design discussion for this feature has been in
<a href="https://github.com/w3c/csswg-drafts/issues/13163">w3c/csswg-drafts#13163</a>.

<h2 id="processing-model">Processing model</h2>

The at rules and pseudo-classes defined in this document rely on the [=current navigation state=].

A <dfn>navigation state</dfn> is a [=struct=] with the following items:

<dl dfn-for="navigation state">
    : <dfn>old URL</dfn>
    : <dfn>new URL</dfn>
    :: a [=/URL=]
    
    : <dfn>type</dfn>
    :: a {{NavigationType}}
    
    : <dfn>old index</dfn>
    : <dfn>new index</dfn>
    :: an integer

    : <dfn>phase</dfn>
    :: `loading`, `ready`, or `committed`.

    : <dfn>source element</dfn>
    :: null or an {{Element}}.
</dl>

<div algorithm>
To get the <dfn>current navigation state</dfn> of a {{Document}} |document|:

1. If |document| is not [=Document/fully active=], return null.

1. Let |navigation| be |document|'s [=relevant global object=]'s [=navigation API=].

1. Let |activation| be |navigation|'s {{Navigation/activation}}.

1. If |document| has not [=has been revealed|been revealed=]:
    1. If |activation| is null, return null.

    1. [=Assert=]: |activation|'s {{NavigationActivation/entry}} is not null.

    1. Return a new [=navigation state=] whose
        [=navigation state/old URL=] is |activation|'s {{NavigationActivation/from}}'s {{NavigationHistoryEntry/url}},
        [=navigation state/new URL=] is |activation|'s {{NavigationActivation/entry}}'s {{NavigationHistoryEntry/url}},
        [=navigation state/type=] is |activation|'s {{NavigationActivation/navigationType}},
        [=navigation state/old index=] is |activation|'s {{NavigationActivation/from}}'s {{NavigationHistoryEntry/index}},
        [=navigation state/new index=] is |activation|'s {{NavigationActivation/entry}}'s {{NavigationHistoryEntry/index}},
        [=navigation state/phase=] is `committed`,
        and [=navigation state/source element=] is null.

    Note: this means that navigations that occur before the page is revealed, e.g. calling {{History/pushState()}} in the head do not reflect in CSS.

1. Let |navigateEvent| be the [=ongoing navigate event=] of |navigation|.

1. Let |phase| be `loading`.

1. If |navigateEvent| is null and |navigation|'s [=traversing navigate event=] is not null:
    1. Set |navigateEvent| to |navigation|'s [=traversing navigate event=].

    1. Set |phase| to `ready`.

1. If |navigateEvent| is null, return null.

1. Return a new [=navigation state=] whose
    [=navigation state/old URL=] is |document|'s [=Document/URL=],
    [=navigation state/new URL=] is |navigateEvent|'s {{NavigateEvent/destination}}'s {{NavigationDestination/url}},
    [=navigation state/type=] is |ongoingNavigateEvent|'s {{NavigateEvent/navigationType}},
    [=navigation state/old index=] is |navigation|'s [=navigation API/current entry=]'s {{NavigationHistoryEntry/index}},
    [=navigation state/new index=] is |navigateEvent|'s {{NavigateEvent/destination}}'s {{NavigationDestination/index}},
    [=navigation state/phase=] is |phase|,
    and [=navigation state/source element=] is |ongoingNavigateEvent|'s {{NavigateEvent/sourceElement}}.

</div>

To get the <dfn>current navigation URL</dfn> given a {{Document}} |document| and a <<navigation-relation>> |relation|:

1. Let |state| be |document|'s [=current navigation state=].
1. If |state| is null, return null.
1. Return the result of switching on |relation|:

<dl class=switch>
: ''to''
:: |state|'s [=navigation state/new URL=].

: ''from''
:: |state|'s [=navigation state/old URL=].

: ''at''
:: |state|'s [=navigation state/new URL=] if |state|'s [=navigation state/phase=] is `committed`; Otherwise |state|'s [=navigation state/old URL=].

: ''with''
:: |state|'s [=navigation state/old URL=] if |state|'s [=navigation state/phase=] is `committed`; Otherwise |state|'s [=navigation state/new URL=].

</dl>

To get the <dfn>current navigation type</dfn> of a [=/document=] |document|:
    1. If |document|'s [=current navigation state=] is non-null, return its [=navigation state/type=].
    1. Return null.

The <dfn>traversing navigate event</dfn> is the [=ongoing navigate event=] which was reset when the [=ongoing navigation=] is set to `traversal`.



ISSUE: Improve integration with the HTML standard, especially the concept of [=traversing navigate event=] and unexported definitions.

<h2 class="no-num" id="privacy">Privacy Considerations</h2>

ISSUE: To be written.

<h2 class="no-num" id="security">Security Considerations</h2>

ISSUE: To be written.