Skip to content

Commit 7201fa3

Browse files
authored
Merge pull request #17 from Semantic-Org/refactor/plugin-imports
Feat: Install a plugin by importing it, as a custom element is define…
2 parents cbeeddb + 20bae77 commit 7201fa3

31 files changed

Lines changed: 1125 additions & 1640 deletions

File tree

‎ai/integrations.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ If this page and the code are not enough to build on, the seam is wrong and not
1818
|---|---|---|
1919
| `Router` | the platform, the page, the cascade (guards, data, titles), the route lifecycle, the settings. Nothing of a route's, nothing of a view's. `router.root` is the root route | `packages/nav-router/src/router.js` |
2020
| `Route` | its data slice, its active life (an abort signal), its reactive runs, and what it shows under `rendered` | `packages/nav-router/src/route.js` |
21-
| a plugin | nothing. `Router.extend(plugin, options)` calls `plugin(options, Router, Navigator)` once; a plugin wraps a moment on a prototype and calls through | `packages/nav-router/src/plugins/*` |
21+
| a plugin | nothing. `import 'nav-router/plugins/x'` is the install, as a custom element's definition is: the module patches a moment on `Router.prototype` or `Navigator.prototype` once, at evaluation, and calls through; its options are the router's, declared on `Router.defaults` and read from `config`. Options are flat, each word qualified enough to stand alone in `router({...})`; a plugin that wants a namespace declares one object-valued key and merges what it is passed over its own defaults itself, since the router's merge is shallow | `packages/nav-router/src/plugins/*` |
2222
| the dom plugin | the native how for the three seams. The reference implementation of this page | `packages/nav-router/src/plugins/dom.js` |
2323
| `ReactiveRouter` | the scaffold a reactive integration extends: the five primitives, slices as per-key stores, hooks in reactions | `packages/nav-router/src/reactive-router.js` |
2424
| an integration | a class extending `Router` or `ReactiveRouter` that fills the seams, in its own package | `@nav-router/<name>` |

‎docs/src/content/docs/plugins/head.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,29 @@
22
title: head
33
kind: plugin
44
lede: Writes each page’s title, meta tags and canonical link into `document.head`, merged down the routes that are active.
5-
import: import head from 'nav-router/plugins/head'
5+
import: import 'nav-router/plugins/head'
66
size: head
77
updated: 2026-11-05
88
---
99

1010
## Install
1111

12-
Extend the router once, before it starts. A plugin wraps one moment in the router and calls through, so installing it changes nothing else.
12+
Import the plugin once. A plugin wraps one moment in the router and calls through, so importing it changes nothing else, and its options are the router's own.
1313

1414
```js title="app.js"
15-
import { Router } from 'nav-router';
16-
import head from 'nav-router/plugins/head';
15+
import 'nav-router/plugins/head';
16+
import { router } from 'nav-router';
1717

18-
Router.extend(head, {
18+
const app = router({
1919
formatTitle: (title) => `${title} · Acme`,
20+
// the routes
2021
});
2122
```
2223

2324
## Options
2425

2526
| Option | Type | Default | Description |
2627
|---|---|---|---|
27-
| `defaults` | `object` | `{}` | Tags every page starts from, before routes add theirs. |
2828
| `formatTitle` | `function` | `null` | Turns a route’s title into the document title. |
2929

3030
## The `meta` route option
Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,7 +8,5 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();
Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,7 +8,5 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();

‎docs/src/content/examples/guards/app.js‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,9 +8,7 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();
1513

1614
const USERS = {
Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,7 +8,5 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();
Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,7 +8,5 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();

‎docs/src/content/examples/query-params/app.js‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
import { Router, router, update } from 'nav-router';
2-
import dom from 'nav-router/plugins/dom';
1+
import 'nav-router/plugins/dom';
2+
import { router, update } from 'nav-router';
33

44
import { routes } from './routes.js';
55

@@ -8,9 +8,7 @@ import { routes } from './routes.js';
88
const base = new URL('.', import.meta.url).pathname.replace(/\/$/, '');
99
/* playground-hide-end */
1010

11-
Router.extend(dom, { mount: '#app' });
12-
13-
const app = router({ base, ...routes });
11+
const app = router({ base, mount: '#app', ...routes });
1412
await app.start();
1513

1614
// the toggle changes the current page's query in place

‎docs/src/lib/home-body.html‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -255,12 +255,8 @@ <h2>Small core, opt-in plugins</h2>
255255
<p>Like day.js, the core does one job and plugins add the rest. Each one wraps a single moment in the router and calls through, so you only ship what you install.</p>
256256
<div class="code">
257257
<pre data-hl>
258-
import { Router } from 'nav-router';
259-
import head from 'nav-router/plugins/head';
260-
import viewTransitions from 'nav-router/plugins/view-transitions';
261-
262-
Router.extend(head);
263-
Router.extend(viewTransitions);
258+
import 'nav-router/plugins/head';
259+
import 'nav-router/plugins/view-transitions';
264260
</pre>
265261
</div>
266262
<a class="text-link" href="#">Browse all plugins</a>

‎docs/src/lib/plugins.js‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -63,20 +63,21 @@ export const PLUGINS = [
6363
// the binding a plugin imports under: view-transitions → viewTransitions
6464
export const bindingFor = (name) => name.replace(/-(\w)/g, (_, c) => c.toUpperCase());
6565

66-
// options a plugin needs to do anything, shown in the setup: dom renders into a mount
67-
const REQUIRED_OPTIONS = { dom: "{ mount: '#app' }" };
66+
// options a plugin needs to do anything, shown in the setup as the router's own: dom renders into a mount
67+
const REQUIRED_OPTIONS = { dom: "mount: '#app'" };
6868

69-
// the setup for a set of plugins, as nav-router's own examples write it, day.js style: one import
70-
// and one Router.extend() per plugin. dom goes first, the renderer the others build on
69+
// the setup for a set of plugins, as nav-router's own examples write it: one import per plugin, for
70+
// its effect, dom first, the renderer the others build on, and the plugins' options on the router
7171
export function sampleFor(names) {
7272
const picked = PLUGINS.map((p) => p.name).filter((n) => names.includes(n))
7373
.sort((a, b) => (b === 'dom') - (a === 'dom'));
74-
const lines = ["import { Router } from 'nav-router';"];
75-
picked.forEach((n) => lines.push(`import ${bindingFor(n)} from 'nav-router/plugins/${n}';`));
76-
lines.push('');
74+
const lines = [];
75+
picked.forEach((n) => lines.push(`import 'nav-router/plugins/${n}';`));
7776
if (!picked.length) { lines.push('// select plugins below to add them here'); }
78-
picked.forEach((n) =>
79-
lines.push(`Router.extend(${bindingFor(n)}${REQUIRED_OPTIONS[n] ? `, ${REQUIRED_OPTIONS[n]}` : ''});`)
80-
);
77+
lines.push("import { router } from 'nav-router';", '');
78+
const options = picked.map((n) => REQUIRED_OPTIONS[n]).filter(Boolean);
79+
lines.push('const app = router({');
80+
options.forEach((option) => lines.push(` ${option},`));
81+
lines.push(' // the routes', '});');
8182
return lines.join('\n');
8283
}

0 commit comments

Comments
 (0)