Skip to content

Commit 1e81fb6

Browse files
authored
Merge pull request #13 from Semantic-Org/docs/framework-guides
Docs: Add Framework Guides to the Sidebar
2 parents 0f1b1f6 + 3da6cee commit 1e81fb6

9 files changed

Lines changed: 235 additions & 16 deletions

File tree

‎docs/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,20 @@ updated: 2026-11-05
5151
---
5252
```
5353

54+
### Framework pages
55+
56+
A page under a framework's folder belongs to that framework alone: `guides/solid/quickstart.md`,
57+
`api/solid.md`. Folders come from `slug` in `src/lib/frameworks.js` (Vanilla JS is `vanilla`).
58+
59+
- **Sidebar:** each framework has its own group in Guides and in API (`FRAMEWORK_GUIDES` and
60+
`FRAMEWORK_API` in `src/lib/nav.js`). The sidebar shows only the reader's framework's groups.
61+
- **Opening one** sets the reader's framework to the page's, as a `?framework=solid` link does.
62+
- **Switching** the picker on one goes to the same page for the new framework
63+
(`guides/solid/quickstart` → `guides/react/quickstart`) when it's written, and otherwise says so
64+
on the page.
65+
- **The pager** on a shared page skips framework pages, and on a framework's page stays with that
66+
framework.
67+
5468
### Conventions
5569

5670
| Write | Get |

‎docs/src/content/docs/api/solid.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: '@nav-router/solid'
3+
lede: Placeholder. The Solid integration's exports, what each one adds over the core, and the version of Solid it needs.
4+
import: import { solidRouter } from '@nav-router/solid'
5+
updated: 2026-11-05
6+
---
7+
8+
:::note[Placeholder]
9+
The outline of the integration's reference while its API settles.
10+
:::
11+
12+
## Exports
13+
14+
`SolidRouter`, the router class for Solid, and `solidRouter()`, which makes one.
15+
16+
## Peer dependencies
17+
18+
`nav-router` and `solid-js`.
19+
20+
## How views are rendered
21+
22+
What a view receives and when it updates, once the integration's API is final.
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
---
2+
title: Solid quickstart
3+
lede: Placeholder. A Solid app on nav-router, from install to a routed page, with views written as Solid components.
4+
import: import { solidRouter } from '@nav-router/solid'
5+
updated: 2026-11-05
6+
---
7+
8+
:::note[Placeholder]
9+
The outline of this page while the Solid integration settles. The headings are the shape, the notes say what each part will cover.
10+
:::
11+
12+
## Install
13+
14+
Install `nav-router`, `@nav-router/solid` and `solid-js`, with Solid's compiler in the build.
15+
16+
## Create the router
17+
18+
`solidRouter()` in place of `router()`: same routes, views written as Solid components.
19+
20+
## A view reads the route
21+
22+
A view gets the route as props: params, query and data, live as the router moves.
23+
24+
## Layouts and slots
25+
26+
A layout component and the pages under it. What a context provider inside a layout does and doesn't reach.
27+
28+
## Next
29+
30+
The pages that build on this: views and props, then shared state.

‎docs/src/layouts/Base.astro‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
// every page: the document, the fonts and tokens, and the theme set before first paint
3+
import { FRAMEWORKS } from '../lib/frameworks.js';
34
import '@fontsource-variable/schibsted-grotesk/wght.css';
45
import '@fontsource/fragment-mono/400.css';
56
import '@fontsource/fragment-mono/400-italic.css';
@@ -8,7 +9,8 @@ import '../styles/tokens.css';
89
import sansLatin from '@fontsource-variable/schibsted-grotesk/files/schibsted-grotesk-latin-wght-normal.woff2?url';
910
import monoLatin from '@fontsource/fragment-mono/files/fragment-mono-latin-400-normal.woff2?url';
1011
11-
const { title, description = 'A thin router on the browser’s Navigation API.', share = true } = Astro.props;
12+
const { title, description = 'A thin router on the browser’s Navigation API.', share = true, pageFramework = null } = Astro.props;
13+
const frameworkIds = FRAMEWORKS.map((f) => f.id);
1214
// the page's share card, rendered at build by pages/og/[...slug].png.js
1315
const path = Astro.url.pathname.replace(/^\/|\/$/g, '');
1416
const image = new URL(`/og/${path || 'index'}.png`, Astro.site);
@@ -47,6 +49,18 @@ const canonical = new URL(Astro.url.pathname, Astro.site);
4749
document.documentElement.dataset.theme = t || (matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark');
4850
})();
4951
</script>
52+
<script is:inline define:vars={{ frameworkIds, pageFramework }}>
53+
// the reader's framework, set before first paint so the sidebar shows the right slots: a
54+
// ?framework= in the link, else the page's own (a Solid page is read as Solid), else the
55+
// reader's last pick. the first two are remembered as the new pick
56+
let fw = new URLSearchParams(location.search).get('framework');
57+
if (!frameworkIds.includes(fw)) { fw = pageFramework; }
58+
try {
59+
if (fw) { localStorage.setItem('nr:framework', fw); }
60+
else { fw = localStorage.getItem('nr:framework'); }
61+
} catch {}
62+
document.documentElement.dataset.framework = frameworkIds.includes(fw) ? fw : frameworkIds[0];
63+
</script>
5064
<slot name="head" />
5165
</head>
5266
<body {...Astro.props.bodyAttrs}>

‎docs/src/layouts/DocsChrome.astro‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,9 @@
44
import { getCollection } from 'astro:content';
55
66
import '../styles/docs.css';
7+
import { FRAMEWORKS, frameworkOf, fwById, swapFramework } from '../lib/frameworks.js';
78
import { navFor } from '../lib/nav.js';
9+
import { logoFor } from '../scripts/framework-logos.js';
810
import DocsTopbar from '../components/DocsTopbar.astro';
911
import Base from './Base.astro';
1012
@@ -17,8 +19,21 @@ const ids = [
1719
const nav = navFor(ids, currentId);
1820
const sectionKey = currentId.split('/')[0];
1921
const section = nav.find((s) => s.key === sectionKey);
22+
23+
// a framework's page (guides/solid/…) and the same page for every other framework, where written,
24+
// so switching the picker on it can follow the reader to theirs
25+
const pageFramework = frameworkOf(currentId);
26+
const written = new Set(ids);
27+
const equivalents = pageFramework
28+
? Object.fromEntries(FRAMEWORKS.map((f) => [f.id, written.has(swapFramework(currentId, f.id)) ? `/${swapFramework(currentId, f.id)}/` : null]))
29+
: null;
30+
// a framework's slots show only while it's the reader's pick; data-framework is set before paint
31+
const fwCss = FRAMEWORKS.map((f) =>
32+
`:root[data-framework="${f.id}"] [data-fw-slot]:not([data-fw-slot~="${f.id}"]) { display: none; }`
33+
).join('\n') + `\n:root:not([data-framework]) [data-fw-slot]:not([data-fw-slot~="${FRAMEWORKS[0].id}"]) { display: none; }`;
2034
---
21-
<Base title={title} description={description} bodyAttrs={{ 'data-section': sectionKey }}>
35+
<Base title={title} description={description} pageFramework={pageFramework} bodyAttrs={{ 'data-section': sectionKey }}>
36+
<Fragment set:html={`<style>${fwCss}</style>`} />
2237
<DocsTopbar nav={nav} sectionKey={sectionKey} />
2338

2439
<div class:list={['docs-shell', { 'is-wide': wide }]}>
@@ -35,8 +50,11 @@ const section = nav.find((s) => s.key === sectionKey);
3550
</div>
3651
)}
3752
{section.groups.map((g) => (
38-
<div class="nav-group">
39-
<h2 class="nav-group-label">{g.label}</h2>
53+
<div class:list={['nav-group', { 'is-framework': g.framework }]} data-fw-slot={g.framework}>
54+
<h2 class="nav-group-label">
55+
{g.framework && <span class="nav-group-logo" set:html={logoFor(g.framework)} />}
56+
{g.label}
57+
</h2>
4058
<ul>
4159
{g.items.map((it) => (
4260
<li>
@@ -53,6 +71,14 @@ const section = nav.find((s) => s.key === sectionKey);
5371
<div class="drawer-scrim"></div>
5472

5573
<div class="docs-main">
74+
{pageFramework && (
75+
<div class="doc fw-notice" role="status" hidden data-fw-notice data-page-framework={pageFramework} data-page-label={fwById(pageFramework).label}>
76+
<script is:inline type="application/json" data-fw-equivalents set:html={JSON.stringify(equivalents)}></script>
77+
<span set:html={logoFor(pageFramework)} />
78+
<p data-fw-notice-text></p>
79+
<button class="btn ghost" type="button" data-fw-back></button>
80+
</div>
81+
)}
5682
<slot />
5783
</div>
5884

‎docs/src/lib/frameworks.js‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// the frameworks a reader can pick, shared by the build (the sidebar's framework slots) and the
2+
// browser (the picker, code variants). `slug` is the framework's folder in a url: a page under
3+
// guides/solid/ or api/solid/ belongs to Solid alone.
4+
5+
export const FRAMEWORKS = [
6+
{ id: 'core', slug: 'vanilla', label: 'Vanilla JS', pkg: null },
7+
{ id: 'react', slug: 'react', label: 'React', pkg: '@nav-router/react' },
8+
{ id: 'preact', slug: 'preact', label: 'Preact', pkg: '@nav-router/preact' },
9+
{ id: 'solid', slug: 'solid', label: 'Solid', pkg: '@nav-router/solid' },
10+
{ id: 'vue', slug: 'vue', label: 'Vue', pkg: '@nav-router/vue' },
11+
{ id: 'svelte', slug: 'svelte', label: 'Svelte', pkg: '@nav-router/svelte' },
12+
{ id: 'semantic', slug: 'semantic', label: 'Semantic UI', pkg: '@nav-router/semantic' },
13+
];
14+
15+
// a code block with no variant for the reader's framework borrows one: preact's is react's, then
16+
// every framework falls back to the core version
17+
export const FALLBACK = { preact: ['react'] };
18+
19+
export const fwById = (id) => FRAMEWORKS.find((f) => f.id === id) ?? FRAMEWORKS[0];
20+
21+
// the framework a page belongs to, from its id (guides/solid/quickstart → solid), or null for a
22+
// page every framework shares
23+
export function frameworkOf(id) {
24+
const segment = id.split('#')[0].split('/')[1];
25+
return FRAMEWORKS.find((f) => f.slug === segment)?.id ?? null;
26+
}
27+
28+
// the same page for another framework: guides/solid/quickstart → guides/react/quickstart
29+
export function swapFramework(id, fw) {
30+
const [section, , ...rest] = id.split('/');
31+
return [section, fwById(fw).slug, ...rest].join('/');
32+
}

‎docs/src/lib/nav.js‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,51 @@
1+
import { frameworkOf, FRAMEWORKS } from './frameworks.js';
12
import { PLUGINS } from './plugins.js';
23

34
// the docs' order. an item points at a page by slug; a slug with no page yet is listed as a stub,
45
// so the shape of the docs is visible before every page exists.
6+
//
7+
// a group with `framework` is that framework's slot: the sidebar shows it only while the reader has
8+
// picked that framework. its pages live under the framework's folder (guides/solid/…), so the same
9+
// page for another framework is found by swapping the folder.
10+
11+
// what changes from one view layer to the next: how views are written and how they read the route.
12+
// the shape is a sketch until the integrations settle
13+
const FRAMEWORK_GUIDES = {
14+
core: [['Views with the dom plugin', 'dom-views'], ['Web components', 'web-components']],
15+
react: [['Quickstart', 'quickstart'], ['Components and hooks', 'components'], [
16+
'Suspense and transitions',
17+
'suspense',
18+
]],
19+
preact: [['Quickstart', 'quickstart'], ['Components and hooks', 'components']],
20+
solid: [['Quickstart', 'quickstart'], ['Views and props', 'views'], ['Shared state', 'state']],
21+
vue: [['Quickstart', 'quickstart'], ['Components and composables', 'components']],
22+
svelte: [['Quickstart', 'quickstart'], ['Components and runes', 'components']],
23+
semantic: [['Quickstart', 'quickstart'], ['Templates and signals', 'templates']],
24+
};
25+
26+
// an integration's own exports, listed only where the package exists
27+
const FRAMEWORK_API = {
28+
solid: [['SolidRouter', 'solid-router', true], ['solidRouter()', 'solid-router-fn', true]],
29+
};
30+
31+
const frameworkGroups = (section) =>
32+
FRAMEWORKS.flatMap((f) => {
33+
const items = section === 'guides'
34+
? FRAMEWORK_GUIDES[f.id] ?? []
35+
: f.pkg
36+
? [['Overview', ''], ...(FRAMEWORK_API[f.id] ?? [])]
37+
: [];
38+
if (!items.length) { return []; }
39+
return [{
40+
label: section === 'api' ? f.pkg : f.label,
41+
framework: f.id,
42+
items: items.map(([title, page, symbol]) => ({
43+
title,
44+
slug: [section, f.slug, page].filter(Boolean).join('/'),
45+
...(symbol && { symbol: true }),
46+
})),
47+
}];
48+
});
549

650
export const SECTIONS = [
751
{
@@ -16,6 +60,7 @@ export const SECTIONS = [
1660
{ title: 'Your first router', slug: 'guides/first-router' },
1761
],
1862
},
63+
...frameworkGroups('guides'),
1964
{
2065
label: 'Routing',
2166
items: [
@@ -40,6 +85,7 @@ export const SECTIONS = [
4085
key: 'api',
4186
label: 'API',
4287
groups: [
88+
...frameworkGroups('api'),
4389
{
4490
label: 'Classes',
4591
items: [
@@ -145,7 +191,11 @@ export function navFor(ids, currentId) {
145191
export function pagerFor(ids, currentId) {
146192
const exists = new Set(ids);
147193
const section = SECTIONS.find((s) => s.key === currentId.split('/')[0]);
148-
const pages = section.groups.flatMap((g) => g.items).filter((it) => !it.slug.includes('#') && exists.has(it.slug));
194+
// a shared page pages through shared pages; a framework's page through those and its own
195+
const fw = frameworkOf(currentId);
196+
const pages = section.groups.flatMap((g) => g.items)
197+
.filter((it) => !it.slug.includes('#') && exists.has(it.slug))
198+
.filter((it) => [null, fw].includes(frameworkOf(it.slug)));
149199
const i = pages.findIndex((it) => it.slug === currentId);
150200
return { prev: pages[i - 1] ?? null, next: pages[i + 1] ?? null };
151201
}

‎docs/src/scripts/site.js‎

Lines changed: 26 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { FALLBACK, FRAMEWORKS, fwById } from '../lib/frameworks.js';
12
import { logoFor } from './framework-logos.js';
23
import { mountSearch } from './search.js';
34

@@ -403,17 +404,7 @@ export function createDropdown(host, { options, value, label, onChange, size = '
403404
variant reached through FALLBACK, else its first. its tabs list only its own variants and switch
404405
that block alone; the picker is the one control that changes the framework everywhere */
405406

406-
export const FRAMEWORKS = [
407-
{ id: 'core', label: 'Vanilla JS', pkg: null },
408-
{ id: 'react', label: 'React', pkg: '@nav-router/react' },
409-
{ id: 'preact', label: 'Preact', pkg: '@nav-router/preact' },
410-
{ id: 'solid', label: 'Solid', pkg: '@nav-router/solid' },
411-
{ id: 'vue', label: 'Vue', pkg: '@nav-router/vue' },
412-
{ id: 'svelte', label: 'Svelte', pkg: '@nav-router/svelte' },
413-
{ id: 'semantic', label: 'Semantic UI', pkg: '@nav-router/semantic' },
414-
];
415-
const FALLBACK = { preact: ['react'] }; // then core, then a block's first variant
416-
const fwById = (id) => FRAMEWORKS.find((f) => f.id === id) ?? FRAMEWORKS[0];
407+
export { FRAMEWORKS };
417408

418409
export function getFramework() {
419410
try {
@@ -428,6 +419,8 @@ export function setFramework(id) {
428419
localStorage.setItem('nr:framework', id);
429420
}
430421
catch {}
422+
// the sidebar's framework slots follow this attribute in css
423+
document.documentElement.dataset.framework = fwById(id).id;
431424
document.dispatchEvent(new CustomEvent('nr:framework', { detail: fwById(id).id }));
432425
}
433426

@@ -521,9 +514,31 @@ export function wireFramework(root = document) {
521514
apply(getFramework());
522515
}
523516

517+
// on a framework's own page (guides/solid/…), picking another framework goes to that framework's
518+
// version of the page when one is written, else says so in place, with the way back
519+
export function wireFrameworkPage(root = document) {
520+
const notice = root.querySelector('[data-fw-notice]');
521+
if (!notice) { return; }
522+
const { pageFramework, pageLabel } = notice.dataset;
523+
const equivalents = JSON.parse(notice.querySelector('[data-fw-equivalents]').textContent);
524+
const text = notice.querySelector('[data-fw-notice-text]');
525+
const back = notice.querySelector('[data-fw-back]');
526+
back.textContent = `Back to ${pageLabel}`;
527+
back.addEventListener('click', () => setFramework(pageFramework));
528+
document.addEventListener('nr:framework', ({ detail: fw }) => {
529+
if (fw !== pageFramework && equivalents[fw]) {
530+
location.assign(equivalents[fw]);
531+
return;
532+
}
533+
notice.hidden = fw === pageFramework;
534+
text.textContent = `This page is for ${pageLabel}. It isn’t written for ${fwById(fw).label} yet.`;
535+
});
536+
}
537+
524538
export function init() {
525539
mountSearch();
526540
wireFramework();
541+
wireFrameworkPage();
527542
wireVariants();
528543
highlightAll();
529544
highlightInline();

‎docs/src/styles/docs.css‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,22 @@
6767
color: var(--text); font-size: var(--fs-xs); line-height: var(--lh-xs); font-weight: 600;
6868
}
6969
.nav-group ul { list-style: none; margin: 0; padding: 0; }
70+
/* a framework's slot: its mark beside the label, so the reader sees whose pages these are */
71+
.nav-group.is-framework .nav-group-label { display: flex; align-items: center; gap: 8px; }
72+
.nav-group-logo { display: inline-flex; color: var(--text-3); }
73+
.nav-group-logo svg { width: 14px; height: 14px; }
74+
75+
/* on a framework's page, when the picker says another framework that has no version of it */
76+
.fw-notice {
77+
display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
78+
margin-bottom: 28px; padding: 12px 12px 12px 16px;
79+
border: 1px solid var(--line-2); border-radius: var(--r-3); background: var(--surface-1);
80+
}
81+
.fw-notice[hidden] { display: none; }
82+
.fw-notice > span { display: inline-flex; color: var(--text-3); }
83+
.fw-notice > span svg { width: 18px; height: 18px; }
84+
.fw-notice p { flex: 1; min-width: 200px; margin: 0; color: var(--text-2); font-size: var(--fs-sm); line-height: var(--lh-sm); }
85+
.fw-notice .btn { --h: 32px; padding: 0 12px; font-size: var(--fs-xs); }
7086
.nav-link {
7187
display: flex; align-items: center; height: 32px; padding: 0 10px;
7288
border-radius: var(--r-2);

0 commit comments

Comments
 (0)