@excom/routable-element 0.1.0

package/.rush/temp/chunked-rush-logs/routable-element.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/routable-element.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/routable-element.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 36.16796899999986
+}

package/.rush/temp/operation/build_docs/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 43.255107000000066
+}

package/.rush/temp/operation/build_package-metas/all.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 92.0411489999999
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/routable-element": "../../packages/routable-element:OaWXFD2rsxm0UKuzafmWeu6jw1vWZUo3lv+Y44mly+A=:"
+}

package/config/rig.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}
+

package/index.ts

@@ -0,0 +1,96 @@
+import { KitRoute, kitRouter } from "@excom/kit-router";
+import { Neutron } from "@excom/neutron";
+
+/**
+ * Composition base that makes an element route-aware. Subclasses implement `routeChanged` to react when the URL matches. Used by `<spa-route>`, `<spa-a>`, and `<spa-manager>`.
+ *
+ * @summary URL matching for Neutron elements.
+ */
+export const RoutableElement = Neutron({
+  tag: "noop-tag",
+  props: {
+    /**
+     * @option
+     * URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`.
+     * @values <path pattern>
+     */
+    routeHref: String,
+    /**
+     * @option
+     * RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns.
+     * @values <RegExp source>
+     */
+    routeRegex: String,
+    /**
+     * @option
+     * Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs.
+     */
+    matchNested: Boolean,
+    routeInstance: KitRoute,
+  },
+})
+  .defineMethods({
+    routeChanged: () => {
+      throw new Error("routeChanged must be implemented");
+    },
+  })
+  .onConnected(
+    ({
+      routeHref,
+      routeRegex,
+      routeChanged,
+      matchNested,
+      isMoving,
+      wasMounted,
+    }) => {
+      if (isMoving) return;
+      return (
+        wasMounted &&
+        (routeHref || routeRegex) && {
+          routeInstance: new KitRoute(
+            (routeHref || new RegExp(routeRegex!))!,
+            routeChanged,
+            {
+              matchNested,
+            }
+          ),
+          _usedRouteProp: "routeHref",
+        }
+      );
+    }
+  )
+  .onDisconnected(({ routeHref, isMoving }) => {
+    if (isMoving) return;
+    return (
+      routeHref && {
+        routeInstance: null,
+      }
+    );
+  })
+  .onPropChanged(
+    ["routeHref", "routeRegex"],
+    ({ routeHref, routeRegex, routeChanged, matchNested }, previous) => {
+      let routeInstance;
+      if (previous?.routeHref || previous?.routeRegex) {
+        // if previous routeInstance was set, remove it
+        routeInstance = null;
+      }
+      if (routeHref || routeRegex) {
+        // if new route, set a new routeInstance, which will also remove the previous one
+        routeInstance = new KitRoute(
+          (routeHref || new RegExp(routeRegex!))!,
+          routeChanged,
+          { matchNested }
+        );
+      }
+      return { routeInstance };
+    }
+  )
+  .onPropChanged("routeInstance", ({ routeInstance }, previous) => {
+    if (previous?.routeInstance) {
+      kitRouter.off(previous.routeInstance);
+    }
+    if (routeInstance) {
+      kitRouter.on(routeInstance);
+    }
+  });

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excom/routable-element",
+  "version": "0.1.0",
+  "description": "RoutableElement base for Neutron elements",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-router": "^0.1.0",
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/routable-element"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/routable-element/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "RoutableElement",
+    "routable-element",
+    "neutron",
+    "kit-element-base",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "element-base"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/routable-element.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/routable-element.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/routable-element.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/routable-element.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/routable-element.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/routable-element.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/support/custom-elements.json

@@ -0,0 +1,100 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "index.ts",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "name": "RoutableElement",
+          "summary": "URL matching for Neutron elements.",
+          "description": "Composition base that makes an element route-aware. Subclasses implement `routeChanged` to react when the URL matches. Used by `<spa-route>`, `<spa-a>`, and `<spa-manager>`.",
+          "attributes": [
+            {
+              "name": "route-href",
+              "type": {
+                "text": "string"
+              },
+              "description": "URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`.",
+              "fieldName": "routeHref",
+              "values": [
+                "<path pattern>"
+              ]
+            },
+            {
+              "name": "route-regex",
+              "type": {
+                "text": "string"
+              },
+              "description": "RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns.",
+              "fieldName": "routeRegex",
+              "values": [
+                "<RegExp source>"
+              ]
+            },
+            {
+              "name": "match-nested",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs.",
+              "fieldName": "matchNested"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "routeHref",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "routeRegex",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "matchNested",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs.",
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "RoutableElement",
+          "declaration": {
+            "name": "RoutableElement",
+            "module": "index.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/dist-docs/routable-element.md

@@ -0,0 +1,99 @@
+# 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`
+- **Nested match** Keep layouts active under child paths
+- **Live updates** Rematch when `route-href` / `route-regex` change
+
+## Installation
+
+
+`@excom/routable-element` v0.1.0
+
+```bash
+pnpm add @excom/routable-element
+```
+
+```bash
+npm install @excom/routable-element
+```
+
+```bash
+yarn add @excom/routable-element
+```
+
+### Import
+
+```ts
+import { /* … */ } from "@excom/routable-element";
+```
+
+
+
+## Usage
+
+Compose `RoutableElement` and implement `routeChanged`. Concrete
+consumers include `<spa-route>`, `<spa-a>`, and `<spa-manager>`.
+
+```ts
+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();
+```
+
+```html
+<path-aware route-href="/dashboard" match-nested></path-aware>
+```
+
+### API Reference
+
+
+#### Attributes
+
+| Name | Surface | Type | Default | Values | Description |
+| --- | --- | --- | --- | --- | --- |
+| `route-href` | option | `string` |  | `<path pattern>` | URL pattern to match. Supports named placeholders (`/users/:id`) and wildcards. Set this or `route-regex`. |
+| `route-regex` | option | `string` |  | `<RegExp source>` | RegExp source string matched against the current URL — alternative to `route-href` for catch-alls / advanced patterns. |
+| `match-nested` | option | `boolean` |  |  | Also match nested paths of `route-href` (e.g. `/users` stays active on `/users/42`). Essential for layout routes and nested SPAs. |
+
+
+
+### Examples
+
+#### Path match & nested layouts
+
+`route-href` activates on exact match; `match-nested` keeps a layout
+mounted under child paths.
+
+```html
+<spa-route route-href="/users" match-nested>
+  <template>…layout…</template>
+</spa-route>
+```
+
+#### Catch-all via regex
+
+```html
+<spa-route route-regex=".*" is-fallback>
+  <template>404</template>
+</spa-route>
+```

package/support/docs/README.md

@@ -0,0 +1,69 @@
+# 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`
+- **Nested match** Keep layouts active under child paths
+- **Live updates** Rematch when `route-href` / `route-regex` change
+
+## Installation
+
+<include-content is-active template-ref="/views/install-section/install-section.html"></include-content>
+
+## Usage
+
+Compose `RoutableElement` and implement `routeChanged`. Concrete
+consumers include `<spa-route>`, `<spa-a>`, and `<spa-manager>`.
+
+```ts
+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();
+```
+
+```html
+<path-aware route-href="/dashboard" match-nested></path-aware>
+```
+
+### API Reference
+
+<include-content is-active template-ref="/views/api-reference/api-reference.html"></include-content>
+
+### Examples
+
+#### Path match & nested layouts
+
+`route-href` activates on exact match; `match-nested` keeps a layout
+mounted under child paths.
+
+```html
+<spa-route route-href="/users" match-nested>
+  <template>…layout…</template>
+</spa-route>
+```
+
+#### Catch-all via regex
+
+```html
+<spa-route route-regex=".*" is-fallback>
+  <template>404</template>
+</spa-route>
+```

package/support/package-meta.json

@@ -0,0 +1,73 @@
+{
+  "shortName": "routable-element",
+  "package": {
+    "name": "@excom/routable-element",
+    "version": "0.1.0",
+    "description": "RoutableElement base for Neutron elements",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "element-base"
+    }
+  },
+  "demos": {},
+  "readme": "<h1 id=\"md-routable-element\">routable-element</h1>\n<p>URL matching for custom elements — give any Neutron class a\n<code>route-href</code> and react when the address bar changes.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Path patterns</strong> Named params (<code>/users/:id</code>) and wildcards</li>\n<li><strong>Regex routes</strong> Full control via <code>route-regex</code></li>\n<li><strong>Nested match</strong> Keep layouts active under child paths</li>\n<li><strong>Live updates</strong> Rematch when <code>route-href</code> / <code>route-regex</code> change</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Compose <code>RoutableElement</code> and implement <code>routeChanged</code>. Concrete\nconsumers include <code>&lt;spa-route&gt;</code>, <code>&lt;spa-a&gt;</code>, and <code>&lt;spa-manager&gt;</code>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { RoutableElement } from \"@excom/routable-element\";\n\nexport const PathAware = Neutron.compose([\n  RoutableElement,\n  Neutron({\n    tag: \"path-aware\",\n    props: {\n      isActive: Boolean,\n    },\n  }),\n])\n  .defineMethods({\n    routeChanged: (_el, { match }) =&gt; ({ isActive: !!match }),\n  });\n\nPathAware.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;path-aware route-href=\"/dashboard\" match-nested&gt;&lt;/path-aware&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-path-match-amp-nested-layouts\">Path match &amp; nested layouts</h4>\n<p><code>route-href</code> activates on exact match; <code>match-nested</code> keeps a layout\nmounted under child paths.</p>\n<include-content data-language=\"html\"><template>&lt;spa-route route-href=\"/users\" match-nested&gt;\n  &lt;template&gt;…layout…&lt;/template&gt;\n&lt;/spa-route&gt;</template></include-content>\n<h4 id=\"md-catch-all-via-regex\">Catch-all via regex</h4>\n<include-content data-language=\"html\"><template>&lt;spa-route route-regex=\".*\" is-fallback&gt;\n  &lt;template&gt;404&lt;/template&gt;\n&lt;/spa-route&gt;</template></include-content>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-routable-element\">routable-element</h1>\n<p>URL matching for custom elements — give any Neutron class a\n<code>route-href</code> and react when the address bar changes.</p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Path patterns</strong> Named params (<code>/users/:id</code>) and wildcards</li>\n<li><strong>Regex routes</strong> Full control via <code>route-regex</code></li>\n<li><strong>Nested match</strong> Keep layouts active under child paths</li>\n<li><strong>Live updates</strong> Rematch when <code>route-href</code> / <code>route-regex</code> change</li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Compose <code>RoutableElement</code> and implement <code>routeChanged</code>. Concrete\nconsumers include <code>&lt;spa-route&gt;</code>, <code>&lt;spa-a&gt;</code>, and <code>&lt;spa-manager&gt;</code>.</p>\n<include-content data-language=\"ts\"><template>import { Neutron } from \"@excom/neutron\";\nimport { RoutableElement } from \"@excom/routable-element\";\n\nexport const PathAware = Neutron.compose([\n  RoutableElement,\n  Neutron({\n    tag: \"path-aware\",\n    props: {\n      isActive: Boolean,\n    },\n  }),\n])\n  .defineMethods({\n    routeChanged: (_el, { match }) =&gt; ({ isActive: !!match }),\n  });\n\nPathAware.define();</template></include-content>\n<include-content data-language=\"html\"><template>&lt;path-aware route-href=\"/dashboard\" match-nested&gt;&lt;/path-aware&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-path-match-amp-nested-layouts\">Path match &amp; nested layouts</h4>\n<p><code>route-href</code> activates on exact match; <code>match-nested</code> keeps a layout\nmounted under child paths.</p>\n<include-content data-language=\"html\"><template>&lt;spa-route route-href=\"/users\" match-nested&gt;\n  &lt;template&gt;…layout…&lt;/template&gt;\n&lt;/spa-route&gt;</template></include-content>\n<h4 id=\"md-catch-all-via-regex\">Catch-all via regex</h4>\n<include-content data-language=\"html\"><template>&lt;spa-route route-regex=\".*\" is-fallback&gt;\n  &lt;template&gt;404&lt;/template&gt;\n&lt;/spa-route&gt;</template></include-content>\n"
+  },
+  "installation": {
+    "name": "@excom/routable-element",
+    "shortName": "routable-element",
+    "version": "0.1.0",
+    "description": "RoutableElement base for Neutron elements",
+    "packageType": "element-base",
+    "install": {
+      "npm": "npm install @excom/routable-element"
+    },
+    "imports": {
+      "js": "import { /* … */ } from \"@excom/routable-element\";"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "summary": "URL matching for Neutron elements.",
+      "kind": "mixin",
+      "attributes": [
+        {
+          "name": "match-nested",
+          "type": "boolean",
+          "description": "Also match nested paths of <code>route-href</code> (e.g. <code>/users</code> stays active on <code>/users/42</code>). Essential for layout routes and nested SPAs.",
+          "fieldName": "matchNested",
+          "surface": "option"
+        },
+        {
+          "name": "route-href",
+          "type": "string",
+          "description": "URL pattern to match. Supports named placeholders (<code>/users/:id</code>) and wildcards. Set this or <code>route-regex</code>.",
+          "fieldName": "routeHref",
+          "surface": "option",
+          "values": "<path pattern>"
+        },
+        {
+          "name": "route-regex",
+          "type": "string",
+          "description": "RegExp source string matched against the current URL — alternative to <code>route-href</code> for catch-alls / advanced patterns.",
+          "fieldName": "routeRegex",
+          "surface": "option",
+          "values": "<RegExp source>"
+        }
+      ],
+      "events": [],
+      "slots": [],
+      "cssProperties": [],
+      "cssClasses": [],
+      "cssAliases": [],
+      "listens": [],
+      "commands": [],
+      "defaultActions": [],
+      "expectedChildren": [],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}

package/support/tests/routable-element-routing.test.ts

@@ -0,0 +1,243 @@
+import { RoutableElement } from "../../index";
+import { Neutron } from "@excom/neutron";
+import { KitRoute, kitRouter } from "@excom/kit-router";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+const TAG = "routable-routing-test";
+
+// Records every `routeChanged` call so tests can assert on router payloads.
+const routeChangedSpy = vi.fn();
+
+const PathAware = Neutron.compose([
+  RoutableElement,
+  Neutron({
+    tag: TAG,
+    props: {
+      isActive: Boolean,
+    },
+  }),
+]).defineMethods({
+  routeChanged: (element, data) => {
+    routeChangedSpy(element, data);
+    return { isActive: !!data.match };
+  },
+});
+
+if (!customElements.get(TAG)) {
+  PathAware.define();
+}
+
+type TestElement = HTMLElement & {
+  routeHref: string | null;
+  routeRegex: string | null;
+  matchNested: boolean;
+  routeInstance: KitRoute | null;
+  isActive: boolean;
+  isMoving: boolean;
+  wasMounted: boolean;
+};
+
+describe("RoutableElement routing", () => {
+  let onSpy: ReturnType<typeof vi.spyOn>;
+  let offSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    history.replaceState(null, "", "/");
+    routeChangedSpy.mockClear();
+    onSpy = vi.spyOn(kitRouter, "on");
+    offSpy = vi.spyOn(kitRouter, "off");
+  });
+
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+    history.replaceState(null, "", "/");
+  });
+
+  it("registers a path route on connect and reacts to URL changes", async () => {
+    const el = fixture<TestElement>(
+      `<${TAG} route-href="/users/:id"></${TAG}>`
+    );
+    await wait(0);
+    expect(el.routeInstance).toBeInstanceOf(KitRoute);
+    expect(el.routeInstance!.key).toBe("/users/:id");
+    expect(onSpy).toHaveBeenCalledWith(el.routeInstance);
+    // registering immediately reports the current (non-matching) URL
+    expect(routeChangedSpy).toHaveBeenLastCalledWith(
+      el,
+      expect.objectContaining({ match: null, params: null })
+    );
+    expect(el.isActive).toBe(false);
+
+    kitRouter.pushState({ url: "/users/7" });
+    expect(routeChangedSpy).toHaveBeenLastCalledWith(
+      el,
+      expect.objectContaining({
+        params: { id: "7" },
+        match: expect.arrayContaining(["/users/7", "7"]),
+        move: "push",
+      })
+    );
+    expect(el.isActive).toBe(true);
+
+    kitRouter.pushState({ url: "/elsewhere" });
+    expect(el.isActive).toBe(false);
+  });
+
+  it("does not register a route when neither route-href nor route-regex is set", async () => {
+    const el = fixture<TestElement>(`<${TAG}></${TAG}>`);
+    await wait(0);
+    expect(el.routeInstance ?? null).toBeNull();
+    expect(onSpy).not.toHaveBeenCalled();
+    expect(routeChangedSpy).not.toHaveBeenCalled();
+    el.remove();
+    await wait(0);
+    expect(offSpy).not.toHaveBeenCalled();
+  });
+
+  it("registers a regex route", async () => {
+    const el = fixture<TestElement>(
+      `<${TAG} route-regex="^/docs(/.*)?$"></${TAG}>`
+    );
+    await wait(0);
+    expect(el.routeInstance!.key).toBeInstanceOf(RegExp);
+    expect(el.routeInstance!.regex.source).toBe(
+      new RegExp("^/docs(/.*)?$").source
+    );
+    expect(el.isActive).toBe(false);
+    kitRouter.pushState({ url: "/docs/intro" });
+    expect(el.isActive).toBe(true);
+  });
+
+  it("honours match-nested", async () => {
+    const nested = fixture<TestElement>(
+      `<${TAG} route-href="/docs" match-nested></${TAG}>`
+    );
+    const exact = fixture<TestElement>(`<${TAG} route-href="/docs"></${TAG}>`);
+    await wait(0);
+    expect(nested.routeInstance!.opts).toEqual({ matchNested: true });
+    expect(exact.routeInstance!.opts).toEqual({ matchNested: false });
+    kitRouter.pushState({ url: "/docs/intro" });
+    expect(nested.isActive).toBe(true);
+    expect(exact.isActive).toBe(false);
+  });
+
+  it("swaps the router registration when route-href changes", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-href="/a"></${TAG}>`);
+    await wait(0);
+    const first = el.routeInstance!;
+    expect(first.key).toBe("/a");
+
+    el.routeHref = "/b";
+    await wait(0);
+    const second = el.routeInstance!;
+    expect(second).not.toBe(first);
+    expect(second.key).toBe("/b");
+    expect(offSpy).toHaveBeenCalledWith(first);
+    expect(onSpy).toHaveBeenCalledWith(second);
+  });
+
+  it("switches from a path route to a regex route", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-href="/a"></${TAG}>`);
+    await wait(0);
+    const pathRoute = el.routeInstance!;
+
+    el.routeHref = null;
+    el.routeRegex = "^/z";
+    await wait(0);
+    expect(offSpy).toHaveBeenCalledWith(pathRoute);
+    expect(el.routeInstance!.key).toBeInstanceOf(RegExp);
+    expect((el.routeInstance!.key as RegExp).source).toBe(
+      new RegExp("^/z").source
+    );
+  });
+
+  it("unregisters when route-href is cleared", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-href="/a"></${TAG}>`);
+    await wait(0);
+    const route = el.routeInstance!;
+    onSpy.mockClear();
+
+    el.routeHref = null;
+    await wait(0);
+    expect(el.routeInstance).toBeNull();
+    expect(offSpy).toHaveBeenCalledWith(route);
+    expect(onSpy).not.toHaveBeenCalled();
+  });
+
+  it("unregisters on disconnect and re-registers on reconnect", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-href="/a"></${TAG}>`);
+    await wait(0);
+    const first = el.routeInstance!;
+
+    el.remove();
+    await wait(0);
+    expect(el.routeInstance).toBeNull();
+    expect(offSpy).toHaveBeenCalledWith(first);
+
+    onSpy.mockClear();
+    document.body.appendChild(el);
+    await wait(0);
+    expect(el.wasMounted).toBe(true);
+    const second = el.routeInstance!;
+    expect(second).toBeInstanceOf(KitRoute);
+    expect(second).not.toBe(first);
+    expect(onSpy).toHaveBeenCalledWith(second);
+  });
+
+  it("re-registers a regex route on reconnect", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-regex="^/r"></${TAG}>`);
+    await wait(0);
+    const first = el.routeInstance!;
+    expect(first).toBeInstanceOf(KitRoute);
+
+    el.remove();
+    await wait(0);
+    onSpy.mockClear();
+    document.body.appendChild(el);
+    await wait(0);
+    const second = el.routeInstance!;
+    expect(second).not.toBe(first);
+    expect(second.key).toBeInstanceOf(RegExp);
+    expect(onSpy).toHaveBeenCalledWith(second);
+  });
+
+  it("does nothing on reconnect when no pattern is set", async () => {
+    const el = fixture<TestElement>(`<${TAG}></${TAG}>`);
+    await wait(0);
+    el.remove();
+    await wait(0);
+    document.body.appendChild(el);
+    await wait(0);
+    expect(el.routeInstance ?? null).toBeNull();
+    expect(onSpy).not.toHaveBeenCalled();
+  });
+
+  it("keeps the registration when the element is moved synchronously", async () => {
+    const el = fixture<TestElement>(`<${TAG} route-href="/a"></${TAG}>`);
+    await wait(0);
+    const route = el.routeInstance!;
+    offSpy.mockClear();
+    onSpy.mockClear();
+
+    const holder = document.createElement("div");
+    document.body.appendChild(holder);
+    // remove + append in the same task is a "move" (isMoving), not a
+    // disconnect: the route must stay registered exactly once
+    el.remove();
+    holder.appendChild(el);
+    await wait(0);
+    expect(el.routeInstance).toBe(route);
+    expect(offSpy).not.toHaveBeenCalled();
+    expect(onSpy).not.toHaveBeenCalled();
+  });
+});

package/support/tests/routable-element.test.ts

@@ -0,0 +1,42 @@
+import { RoutableElement } from "../../index";
+import {
+  afterEach,
+  describe,
+  expect,
+  fixture,
+  it,
+  vi,
+  wait,
+} from "@excom/heft-rig/profiles/default/config/test-utils";
+
+const TAG = "routable-element-test";
+if (!customElements.get(TAG)) {
+  RoutableElement.define(TAG);
+}
+
+describe("RoutableElement", () => {
+  afterEach(() => {
+    document.body.innerHTML = "";
+    vi.restoreAllMocks();
+  });
+
+  it("throws when routeChanged is not implemented", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    expect(() => el.routeChanged()).toThrowError(/routeChanged/);
+  });
+
+  it("has default props", () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    expect(el).dom.to.equalTag(`<${TAG}></${TAG}>`);
+  });
+
+  it("sets routeInstance to null on disconnect when routeHref is set", async () => {
+    const el = fixture<any>(`<${TAG}></${TAG}>`);
+    el.routeChanged = vi.fn();
+    el.routeHref = "/test";
+    await wait(0);
+    el.remove();
+    await wait(0);
+    expect(el.routeInstance).toBeNull();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@excom/heft-rig/profiles/default/config/tsconfig.json",
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}