HTML route-matching syntax

[noamr]

The explainer for route-matching describes the main use cases and features of route matching, but details of the exact syntax remain open.

This is in conjunction with w3c/csswg-drafts#12594, where the CSS syntax is discussed.

Principles / key questions

Format

The route map can be:

• JSON (as in the explainer and in speculation rules)
• JS object building (like in service-worker static routing)
• an xml-like element tree (probably not a contender in 2025)
• Reusing the CSS at-rule syntax

What goes in a single rule

Like in service-worker static routing, a rule has a "condition" that defines whether it matches a URL or a navigation, and a set of descriptors that apply when that condition applies.

A condition tests for:

1. A URLPattern with
2. a navigation affinity for this URL, which can be one of current | other | old | new
3. Scope of the source element or the element being styled

A condition can also be a logical combinator of multiple conditions (or/and/not).

When in HTML, the descriptors are (when considering some future enhancements):

• Name (for logical combinators and for CSS)
• History (push, replace or none)
• Mode (intercept vs. passthrough)
• Auto-patching (a URL?)

When in CSS, the descriptors can be any CSS rule, as the route become a "conditional".
In addition, links can match a particular route.

Querying & composing

There are two main precedences for logical combinators, all seeming relevant:

• CSS conditionals already provide logical combinators (not, and, only, and comma for or).
• Speculation rules & service worker static routing use {not: condition} and {or: [condition, condition]} for combinators.

Event handling

The main events fired for routes are match/unmatch/prepare/cleanup (to be bikeshed).

This applies to a rule after resolving its combinators.

1. JSON with pure-JSON combinators

[
  { "name": "article", "condition": { "urlPattern": { "pathname": "/article/:aid" } } },
  { "name": "content", "condition": { "or": ["article", "feed" ] } }
]

This is pure and consistent with existing route-like capabilities, but is on a different field from CSS.

2. JSON with media-style querying

[
  { "name": "article", "condition": { "urlPattern": { "pathname": "/article/:aid" } } },
  { "name": "content", "condition": { "query": "at article, at feed, to content[aid=foo]"] } }
]

This is a more expressive query syntax, and is consistent with how CSS is going to query for routes.

Also it is a convenient way to register to events in a granular way:

documentOrElement.matchRoute("article[aid=1], feed").addEventListener("prepare", e => { 
  // prepare content
});

3. Allow both

Using or, and and query is not colliding syntactically (though perhaps colliding in terms of mental model). We could potentially allow both?

4. Fully CSS

Allow a CSS like syntax, without it being a style:

@route route-name (from article, to feed, urlpattern(pathname: "/content")) {
  history: push;
  mode: intercept;
}

This is very expressive and aligns with the intention of routes as a UI-first feature, but is not consistent with other "route" related features.

5. JS

Instead of using JSON or CSS, use JS initialization:

documentOrElement.routeMap.add({
  condition, name, history, mode
});

This needs to be in conjunction with resolving the query question.

The main disadvantage of this is that it is not static, and requires running scripts on the page imperatively to make work.

[noamr]

Based on discussions up until now, suggesting to be as close as possible to service-worker static routing, and have the same "condition" syntax (or as similar as possible) for logical combinators (and/or/not).
Then CSS can define the navigation combinator (to/from/at) on top, in a way similar to @scroll-state.