routable-element
URL matching for custom elements — give any Neutron class a
route-href and react when the address bar changes.
Features
- Path patterns Named params (
/users/:id) and wildcards - Regex routes Full control via
route-regex(ignored whenroute-hrefis set); named groups ((?<id>\d+)) becomeparams, in a path pattern too, unnamed ones stay inmatch - Nested match Keep layouts active under child paths
- Live updates Rematch when
route-href/route-regexchange
Installation
This package is available in the
<script src="https://unpkg.com/@excom/kit-utils@0.3.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/neutron@0.2.0/dist/index.umd.min.js"></script>
<script src="https://unpkg.com/@excom/routable-element@0.2.2/dist/index.umd.min.js"></script>npm install @excom/routable-elementimport { /* … */ } from "@excom/routable-element";Peer dependencies (0)
Packages a consumer must install alongside this one. Workspace deps are bundled.
| Package | Version |
|---|---|
|
Usage
Compose RoutableElement and implement routeChanged. Concrete
consumers include <spa-route>, <spa-a>, and <spa-manager>.
import { Neutron } from "@excom/neutron";
import { RoutableElement } from "@excom/routable-element";
export const PathAware = Neutron.compose([
RoutableElement,
Neutron({
tag: "path-aware",
props: {
isActive: Boolean,
},
}),
])
.defineMethods({
routeChanged: (_el, { match }) => ({ isActive: !!match }),
});
PathAware.define();import { Neutron } from "@excom/neutron";
import { RoutableElement } from "@excom/routable-element";
export const PathAware = Neutron.compose([
RoutableElement,
Neutron({
tag: "path-aware",
props: {
isActive: Boolean,
},
}),
])
.defineMethods({
routeChanged: (_el, { match }) => ({ isActive: !!match }),
});
PathAware.define();<path-aware route-href="/dashboard" match-nested></path-aware><path-aware route-href="/dashboard" match-nested></path-aware>API Reference
Attributes
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
Provision
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements
Child or descendant elements are recognized by and relevant to its functionality.Styles
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
Attributes (3)
Role —option is configurable, state
is managed by the element (read-only), or hybrid which is both.
match-nested
Also match child paths of
route-href: /users matches /users and /users/42, never /usersx. Essential for layout routes and nested SPAs.
matchNested
boolean
falseroute-href
URL pattern to match. Supports named placeholders (
/users/:id) and wildcards: *rest matches one path segment, a bare * across segments. A relative pattern (checkout) resolves against the page's <base>; without one, against the page URL at registration. Set this or route-regex; with both, this one wins.
routeHref
string
<path pattern>nullroute-regex
RegExp source string matched against the pathname (never the query or hash) — alternative to
route-href for catch-alls / advanced patterns, ignored when route-href is set. Here and in a route-href, named groups become params ((?<id>\d+) → params.id); unnamed groups stay in match.
routeRegex
string
<RegExp source>nullProvision (0)
Thisprovision property lives on the DOM node.
Read / watch it with Quark’s prop("provision"), or listen
for the neutron-provision event from app JS.
Events (0)
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
Type
command event (HTML Command API): from a
<button command commandfor>, an <event-handler
command-name>, or a CommandEvent.
Recognized Elements (0)
Child or descendant elements are recognized by and relevant to its functionality.Styles (0)
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
@custom-selector synonyms so custom elements can share
semantic styles. Element aliases match the host tag / .tag-* class; state
aliases match attributes (nested under the element alias).
Release notes (2)
0.2.0
- Update
match-nestedto match its own path as well as child paths:route-href="/users"is active at/users, so a separate route for that path renders beside it and a 404 fallback stays off there - Add relative
route-hrefvalues:checkoutresolves against the page's<base>, or against the page URL at registration when there is none - Fix an issue where a routable element inside
persist-contentthrew aNeutronErrorwhen re-attached - Fix an issue where an element given a
route-hrefwhile detached registered a route, and aroute-regexelement stayed registered after it was removed - Fix an issue where changing
match-nestedat runtime had no effect
0.1.1
- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources
Release notes
A "default action" is subsequent logic executed by the element if
e.preventDefault() is not
synchronously called on the event.
If you wish to opt-out of these styles on a case-to-case basis, use property
all: revert-layer.
Valence.css ships this as .unstyled and .unstyled-all for the entire tree.
Examples
Path match & nested layouts
route-href activates on exact match; with match-nested it also matches child paths, keeping a layout mounted.
<spa-route route-href="/users" match-nested>
<template>…layout…</template>
</spa-route><spa-route route-href="/users" match-nested>
<template>…layout…</template>
</spa-route>Catch-all via regex
<spa-route route-regex=".*" is-fallback>
<template>404</template>
</spa-route><spa-route route-regex=".*" is-fallback>
<template>404</template>
</spa-route>