Skip to content

Replace css-route-matching draft with link to its new location. #71

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dbaron merged 1 commit into from
Nov 19, 2025
Merged

Replace css-route-matching draft with link to its new location. #71

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 4 additions & 296 deletions css-route-matching/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,301 +10,9 @@ Repository: WICG/declarative-route-matching
ED: https://wicg.github.io/declarative-partial-updates/css-route-matching/
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 based on routes
declared in HTML. This allows styles to be conditioned on the current URL
or conditioned on the status of navigating between particular URLs.
No Abstract: true
Boilerplate: references no, status no, conformance no
</pre>
<!-- for now using Org: w3c rather than Group: csswg because the latter forces an incorrect issue tracking link, overriding Repository -->

<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#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;
</pre>

<h2 id="condional-route-queries">Conditional rules for route queries</h2>

<h3 id="at-route">Route queries: the ''@route'' rule</h3>

The <dfn at-rule id="at-ruledef-route">@route</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>route 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 ''@route'' 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 ''@route'' rule is:

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

with <<route-condition>> defined as:

<pre class="prod def" dfn-type="type" nohighlight>
<dfn><<route-condition>></dfn> = not <<route-in-parens>>
| <<route-in-parens>> [ and <<route-in-parens>> ]*
| <<route-in-parens>> [ or <<route-in-parens>> ]*
<dfn><<route-in-parens>></dfn> = ( <<route-condition>> ) | ( <<route-test>> ) | <<general-enclosed>>
<dfn><<route-test>></dfn> = <<route-location>> | <<route-keyword>> : <<route-location>>
<dfn><<route-keyword>></dfn> = at | from | to
<dfn><<route-location>></dfn> = <<urlpattern()>>
</pre>

The above grammar is purposely very loose for forwards-compatibility reasons,
since the <<general-enclosed>> production
allows for substantial future extensibility.
Any ''@route'' 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:

: <<route-condition>>
:: : not <<route-in-parens>>
:: The result is the negation of the <<route-in-parens>> term.

: <<route-in-parens>> [ and <<route-in-parens>> ]*
::
The result is true if all of the <<route-in-parens>> child terms are true,
and false otherwise.

: <<route-in-parens>> [ or <<route-in-parens>> ]*
::
The result is false if all of the <<route-in-parens>> child terms are false,
and true otherwise.

: <<route-in-parens>>
:: The result is the result of the child subexpression.

: <<route-test>>
:: : <<route-location>>
: at: <<route-location>>
:: The result is true if
the document's [=Document/URL=] [=URL pattern/match|matches=]
the [=route location URL pattern=] of <<route-location>>.

: from: <<route-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 {{NavigationHistoryEntry/url}}
is non-null and
[=URL pattern/match|matches=]
the [=route location URL pattern=] of <<route-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 {{NavigationActivation/from}}'s
{{NavigationHistoryEntry/url}}'s
is non-null and
[=URL pattern/match|matches=]
the [=route location URL pattern=] of <<route-location>>.

: to: <<route-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 {{NavigateEvent/destination}}'s
{{NavigationDestination/url}}
[=URL pattern/match|matches=]
the [=route location URL pattern=] of <<route-location>>.

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
<a href="https://github.com/whatwg/html/issues/11690">whatwg/html#11690</a> /
<a href="https://github.com/whatwg/html/pull/11692">whatwg/html#11692</a>.
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 {{NavigationActivation/entry}}'s
{{NavigationHistoryEntry/url}}'s
is non-null and
[=URL pattern/match|matches=]
the [=route location URL pattern=] of <<route-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.

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.

ISSUE: 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.
<span class='note'>It exists only for future-compatibility,
so that new syntax additions do not invalidate too much of a <<route-condition>> in older user agents.</span>

The <dfn>route location URL pattern</dfn> of a <<route-location>>
depends on the type of <<route-location>>:

: <<urlpattern()>>
:: The [=URL pattern=] represented by the function; see
[=create a URL pattern for urlpattern()=].

ISSUE: There is currently only one type of <<route-location>>
but we should consider adding another,
which would be just a name that references
a name defined in a routemap.
See the
<a href="https://github.com/WICG/declarative-partial-updates/blob/main/route-matching-explainer.md">route matching explainer</a>
for details.

A <dfn>document's navigation API</dfn> is
the result of the following steps on <var>document</var>:

1. Let <var>window</var> be the {{Window}} whose [=associated Document=] is <var>document</var>, or null if there is no such {{Window}}.

1. If <var>window</var> is null, return null.

1. Return <var>window</var>'s [=navigation API=].

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

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

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

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

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

<h3 id="route-if-function">The ''if()/route()'' 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>route()</dfn> = route( <<route-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-route-pseudo-classes">Pseudo-classes for route-related links</h2>

TODO: To be written.

<h2 id="urlpattern-function">The ''urlpattern()'' function</h2>

<!--

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>urlpattern()</dfn> function represents a [=URL pattern=],
which can be used to match URLs.

<pre class="prod def">
<<urlpattern()>> = urlpattern( <<string>> )
</pre>

This function represents a [=URL pattern=] that can be created
using the steps of the <dfn>create a URL pattern for urlpattern()</dfn> algorithm:

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

1. Let <var>baseURL</var> be the [=style resource base URL=] of
the rule or declaration block containing the ''urlpattern()'' function.

<div class="issue">
Do we want this to be the base URL all the time?
For use of ''urlpattern()'' in ''@route'',
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 <code>document-urlpattern()</code>?
Should we do something similar to
[[css-images-3#ambiguous-urls]]
(see <w3c/csswg-drafts#383>)?

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

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.

To <dfn export>serialize a ''urlpattern()'' 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.
This specification has moved to
<a href="https://drafts.csswg.org/css-navigation-1/">https://drafts.csswg.org/css-navigation-1/</a>.