@snapstrat/switchboard 1.0.0

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SnapStrat Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,323 @@
+<div align="center">
+    <h1><img alt="SwitchBoard Logo" width="480" src="switchboard-logo.png"/></h1>
+    <p><i>A simple, extensible, component-based Svelte 5 SPA router.</i></p>
+    <img alt="License" src="https://img.shields.io/github/license/snapstrat/switchboard">
+</div>
+
+# Features
+
+- A declarative, component-based method to declare routes.
+- A simple API to programmatically navigate between routes.
+- Layouts, nested routes, and route parameters.
+- Svelte 5 compatibility, with TypeScript support.
+
+# Why Switchboard?
+
+Switchboard is designed to be a simple, extensible router for Svelte 5 applications. 
+Using composition and a declarative API, developers are able to quickly create SPA routes without the complexity of larger routing libraries, or dealing with SSR.
+
+Switchboard is ideal for applications which:
+- don't require server-side rendering. See [Use with SvelteKit](#use-with-sveltekit) for more info.
+- want a simple, component-based routing solution.
+- want to stray away from strictly file-based routing systems, such as SvelteKit's routing.
+- want more flexibility in defining routes and layouts.
+- want to be able to define routes in a way that fits their application's architecture.
+
+# Getting Started
+
+To install Switchboard, run:
+
+```sh
+# npm
+npm install @snapstrat/switchboard
+# yarn
+yarn add @snapstrat/switchboard
+# pnpm
+pnpm install @snapstrat/switchboard
+# bun
+bun install @snapstrat/switchboard
+```
+
+# Basic Usage
+
+Switchboard exposes several components and functions to help you set up routing in your Svelte application.
+
+## Creating a Router
+Switchboard leaves the router setup to you. You can either use some form of global state management to hold a reference to it,
+or create it directly in your root component.
+
+Switchboard includes a `createWebRouter()` function to create a router instance that works with the browser's history API.
+
+### Global Access
+> main.ts
+
+```ts
+import App from './App.svelte';
+import { createWebRouter } from '@snapstrat/switchboard';
+
+// now anything can import router from here to access the router!
+export const router = createWebRouter();
+
+mount(App, {
+	target: document.body,
+});
+```
+
+### Creation in Root Component
+> App.svelte
+```svelte
+<script lang="ts">
+	import { BrowserRouter, createWebRouter } from '$lib';
+	import PersistenceLayout from './PersistenceLayout.svelte';
+
+    // we can also create the router here!
+	const router = createWebRouter()
+</script>
+
+<!-- all BrowserRouter needs is a Router instance, constructed from anywhere. -->
+<!-- any component nested in BrowserRouter gets access to getRouter() using Svelte contexts. -->
+<BrowserRouter {router}>
+    <!-- Your routes and layouts go here -->
+</BrowserRouter>
+```
+
+## Defining Routes
+Switchboard is very unopinionated about how you define your routes. 
+The main building blocks are the `Route`, `Layout`, `PageInfo` and `Link` components.
+
+```svelte
+<script lang="ts">
+    import { BrowserRouter, Route, Link } from '@snapstrat/switchboard'
+    
+    // maybe make a router here? or import one.
+</script>
+
+<BrowserRouter router={your_router_instance}>
+    <Route path="/">
+        <h1>Home Page</h1>
+    </Route>
+
+    <Route path="/users/:id">
+        <h1>You're looking for a user with the id: {getRouteParams().id}</h1>
+    </Route>
+    
+    <!-- You can use Route404 to catch all unmatched routes -->
+    <Route404>
+        <h1>404 - Page Not Found</h1>
+    </Route404>
+</BrowserRouter>
+```
+
+### Links
+Links can be created using the `Link` component, which is a very, very thin wrapper around an `<a>` tag.
+Alternatively, you can use the `Router.switchTo()` method to programmatically navigate between routes, or use
+the `{@attach href('my/path')}` attachment to attach hrefs to any element.
+
+```svelte
+
+<script lang="ts">
+	import { Link } from '@snapstrat/switchboard';
+</script>
+
+<!-- both are equivalent: -->
+<Link href="/some/path">Go to Some Path</Link>
+<a {@attach href("/some/path")}>Go to Some Path</a>
+
+<!-- not recommended for accessibility, but possible: -->
+<button on:click={() => router.switchTo('/some/path')}>
+    Go to Some Path
+</button>
+
+<!-- not recommended at all, this will reload the page and lose SPA state: -->
+<a href="/some/path">Go to Some Path</a>
+```
+
+### PageInfo
+
+The `PageInfo` component allows you to declaratively set metadata for the current page, such as the document title and meta tags.
+
+```svelte
+<script lang="ts">
+    import { PageInfo, Route } from '@snapstrat/switchboard';
+</script>
+
+<Route path="/my-cool-page">
+    <PageInfo title="My Page Title" icon="/page-icon.ico" />
+</Route>
+```
+
+### Layouts 
+Layouts can be used to simplify routes that share common structure. State of a layout
+will persist between __nested__ route changes. 
+For example, if you start at `/user/1`, modify some state in the layout, then navigate to `/user/1/profile`, the layout state will persist.
+However, if you navigate to `/user/2`, or `/`, or `/any-other-route-outside-of-this-layout` the layout will be re-created and state will be destroyed since the route parameter changed.
+
+```svelte
+<BrowserRouter router={your_router_instance}>
+    <!-- Layouts can have parameters too! -->
+    <!-- Layouts have two snippets they take in: `routes` and `layout` -->
+    <Layout path="/user/:id">
+        <!-- layout() holds the common layout structure. -->
+        {#snippet layout(route: Snippet)}
+            <p>You're looking at something for {getRouteParams().id}!</h1>
+            {@render route()}
+        {/snippet}
+        
+        <!-- routes() holds all nested routes -->
+        {#snippet routes()}
+            <Route path="profile">
+                <h2>This is the profile page for user {getRouteParams().id}!</h2>
+            </Route>
+            
+            <Route path="settings">
+                <h2>This is the settings page for user {getRouteParams().id}!</h2>
+            </Route>
+            
+            <!-- in this context, / will match for /user/:id/ -->
+            <Route path="/">
+                <h2>This is the settings page for user {getRouteParams().id}!</h2>
+            </Route>
+            
+            <!-- You can also have a Route404 for unmatched nested routes. -->
+            <Route404>
+                <h1>404 - User Not Found</h1>
+            </Route404>
+        {/snippet}
+    </Layout>
+    
+    <!-- You can use Route404 to catch all unmatched routes. -->
+    <Route404>
+        <h1>404 - Page Not Found</h1>
+    </Route404>
+</BrowserRouter>
+```
+
+## Use with SvelteKit
+Switchboard is primarily designed for client-side routing in Svelte applications, and does NOT support server-side rendering (SSR), nor do we plan to ever support SSR.
+
+However, you can still use Switchboard within a SvelteKit application for client-side routing needs. To do this, you'll need two main things:
+1. A single, top-level SvelteKit route that will serve as the entry point for your Switchboard-powered SPA.
+2. SSR disabled for that route.
+
+In practice, this looks like:
+```
+- /src
+  - /routes
+    - /[...any]            <-- catch-all used to route all traffic your only +page.svelte, containing your Switchboard app
+      - +page.svelte      <-- your Switchboard app goes here
+      - +page.ts          <-- disable SSR here with `export const ssr = false;`
+```
+
+In a normal Svelte application, you don't need to worry about any of this, and can just place a `BrowserRouter` at the root of your component tree (probably in `App.svelte`).
+
+# Advanced Usage
+Advanced usage of Switchboard comes from the natural composition of its components. You can create your own custom route components, layouts, and even
+extend the router itself to add functionality.
+
+Any Route or Layout can be declared anywhere that is within a `BrowserRouter`, or a `Layout` component, and will function as expected, no matter how these
+are nested, constructed, composed, or imported.
+
+## Custom Route Component
+You can wrap around the `Route` component to create your own custom route components. 
+
+For example, you could create an authenticated route component that checks if a user is logged in before rendering the route.
+
+> [!CAUTION]
+> Note that this isn't inherently secure, as all routing is done client-side. Make sure that when dealing with sensitive data, you also have server-side checks in place.
+
+> AuthenticatedRoute.svelte
+```svelte
+<script lang="ts">
+    import { Route, getRouter } from '@snapstrat/switchboard';
+    import { onMount } from 'svelte';
+    import { isUserAuthed } from './auth'; // your auth logic here
+    
+    const { children, path } = $props();
+</script>
+
+<Route path={path}>
+    {#if isUserAuthed()}
+        {@render children()}
+    {:else}
+        <h1>Please log in to access this page.</h1>
+    {/if}
+</Route>
+```
+
+> App.svelte
+```svelte
+<script lang="ts">
+    import { BrowserRouter } from '@snapstrat/switchboard';
+    import AuthenticatedRoute from './AuthenticatedRoute.svelte';
+</script>
+
+<BrowserRouter router={your_router_instance}>
+    <AuthenticatedRoute path="/dashboard">
+        <h1>Welcome to your dashboard!</h1>
+    </AuthenticatedRoute>
+</BrowserRouter>
+```
+
+## Escaping Layouts
+If you need to escape a layout for a specific route, you can set a custom 'container' on any route.
+
+```svelte
+<script lang="ts">
+    import { BrowserRouter, Layout, LayoutData, Route } from '@snapstrat/switchboard';
+    
+    let otherLayout: LayoutData = $state();
+</script>
+
+<BrowserRouter router={your_router_instance}>
+    <Layout path="/app">
+        {#snippet layout(route: Snippet)}
+            <div class="app-layout">
+                <nav>...navigation...</nav>
+                <main>
+                    {@render route()}
+                </main>
+            </div>
+        {/snippet}
+        
+        {#snippet routes()}
+            <Route path="dashboard">
+                <h1>Dashboard</h1>
+            </Route>
+            
+            <Route path="settings">
+                <h1>Settings</h1>
+            </Route>
+            
+            <!-- 
+            container can either be a Router instance or another Layout.
+            setting to whatever your router instance is completely disables the layout. 
+             -->
+            <Route path="/login" container={your_router_instance}>
+                <h1>Login Page</h1>
+            </Route>
+            
+            
+            <!--
+            setting container to another layout makes the route use that layout instead 
+            of the current one.
+            
+            note that this will NOT impact the path; this route still exists 
+            at /app/landing-page, NOT /other/landing-page.
+            -->
+            <Route path="/landing-page" container={outerLayout}>
+                <h1>Landing Page</h1>
+            </Route>
+        {/snippet}
+    </Layout>
+    
+    <Layout path="/other" bind:ref={otherLayout}>
+        <!-- another layout... -->
+    </Layout>
+</BrowserRouter>
+```
+
+The same principle can be applied to Layouts nested within other Layouts as well, with the same `container` prop, and
+same rules regarding how paths are resolved. 
+
+> [!WARNING]
+> When escaping a layout, you **must** have the layout you're referencing defined above the layout you're escaping from.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './router';
+export { createWebRouter } from "./router/impl";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Reexport your entry components here
+export * from './router';
+export { createWebRouter } from "./router/impl";

package/dist/router/BrowserRouter.svelte

@@ -0,0 +1,64 @@
+<!--
+@component
+The BrowserRouter component is the main entry point for routing in an application using Switchboard.
+It initializes the routes, listens for changes in the URL to switch routes accordingly,
+and displays the appropriate component based on the current route.
+-->
+<script module lang="ts">
+  import type { Router } from './router.svelte';
+  import type { Snippet } from 'svelte';
+
+  export type PageRouterProps = {
+    /**
+     * The router instance that manages the application's routes.
+     *
+     * @see {@link Router}
+     * @see {@link createWebRouter}
+     */
+    router: Router;
+    children?: Snippet;
+  };
+</script>
+
+<script lang="ts">
+  import { onMount, tick } from 'svelte';
+  import { setRouterContext, type LayoutData, getAllLayouts, Route404 } from './index';
+  import { parseWindowSearchParams } from './internals/windowUtils';
+
+  let { router, children }: PageRouterProps = $props();
+
+  onMount(async () => {
+    await tick();
+    const params = parseWindowSearchParams();
+
+    router.switchTo(window.location.pathname, params, false);
+  });
+
+  setRouterContext(router);
+
+  const currentAppRoute = $derived(router.currentRoute?.route);
+  const layouts = $derived(getAllLayouts(currentAppRoute?.layout));
+</script>
+
+<Route404>
+  <!-- This is blank because it's simply a fallback in case there is no 404 page -->
+  <svelte:fragment />
+</Route404>
+
+{@render children?.()}
+
+{#snippet layoutRender(remaining: LayoutData[])}
+  {#if remaining.length === 0}
+    {@render currentAppRoute?.component?.()}
+  {:else}
+    {@const next = remaining[0]}
+
+    {#snippet renderer()}
+      {@render layoutRender(remaining.slice(1))}
+    {/snippet}
+
+    {@render next.renderer(renderer)}
+  {/if}
+{/snippet}
+
+{@render layoutRender(layouts)}

package/dist/router/BrowserRouter.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Router } from './router.svelte';
+import type { Snippet } from 'svelte';
+export type PageRouterProps = {
+    /**
+     * The router instance that manages the application's routes.
+     *
+     * @see {@link Router}
+     * @see {@link createWebRouter}
+     */
+    router: Router;
+    children?: Snippet;
+};
+/**
+ * The BrowserRouter component is the main entry point for routing in an application using Switchboard.
+ * It initializes the routes, listens for changes in the URL to switch routes accordingly,
+ * and displays the appropriate component based on the current route.
+ */
+declare const BrowserRouter: import("svelte").Component<PageRouterProps, {}, "">;
+type BrowserRouter = ReturnType<typeof BrowserRouter>;
+export default BrowserRouter;

package/dist/router/Layout.svelte

@@ -0,0 +1,79 @@
+<script lang="ts" module>
+
+	import type { Snippet } from 'svelte';
+	import type { LayoutSnippet, RouteContainer } from './router.svelte';
+
+	export type LayoutProps = {
+		path: string;
+		layout: LayoutSnippet;
+		container?: RouteContainer;
+		routes: Snippet;
+		ref?: LayoutData;
+	}
+</script>
+
+<script lang="ts">
+
+	import {
+		type ApplicationRoute, getAllCanonicalLayouts,
+		getLayout,
+		getRouter,
+		type LayoutData,
+		RoutePath,
+		type Router
+	} from '..';
+	import { setLayoutContext } from '..';
+	import { onDestroy } from 'svelte';
+
+	let { path, layout: renderer, container, routes, ref = $bindable() }: LayoutProps = $props();
+
+	type LayoutInternals = { routes: ApplicationRoute[], _routes: ApplicationRoute[] }
+
+	let parent: LayoutData | undefined;
+	if (!container) {
+		parent = getLayout();
+	} else {
+		parent = container.isRouter() ? undefined : container as LayoutData;
+	}
+
+	const layoutData: LayoutData & LayoutInternals = {
+		_routes: [],
+		get routes() {
+			return this._routes.toReversed();
+		},
+		path: path ? RoutePath.normalizePath(path) : undefined,
+		parent,
+		canonicalParent: getLayout(),
+		registerRoute(route: ApplicationRoute) {
+			getRouter().registerRoute(route);
+			this._routes.push(route);
+		},
+		registerRoute404(route: ApplicationRoute) {
+			getRouter().registerRoute404(route);
+			this._routes.push(route);
+		},
+		unregisterRoute(route: ApplicationRoute) {
+			getRouter()?.unregisterRoute(route);
+			this._routes.splice(this.routes.indexOf(route), 1);
+		},
+		renderer,
+		get joinedPath() {
+			return getAllCanonicalLayouts(this)
+				.map((l) => l.path)
+				.filter((p) => p !== undefined && p !== '')
+				.join('/');
+		},
+		isRouter(): this is Router { return false; }
+	}
+	ref = layoutData;
+
+	setLayoutContext(layoutData);
+
+	onDestroy(() => {
+		setLayoutContext(layoutData.parent);
+	})
+</script>
+
+
+
+{@render routes()}

package/dist/router/Layout.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from 'svelte';
+import type { LayoutSnippet, RouteContainer } from './router.svelte';
+export type LayoutProps = {
+    path: string;
+    layout: LayoutSnippet;
+    container?: RouteContainer;
+    routes: Snippet;
+    ref?: LayoutData;
+};
+import { type LayoutData } from '..';
+declare const Layout: import("svelte").Component<LayoutProps, {}, "ref">;
+type Layout = ReturnType<typeof Layout>;
+export default Layout;

package/dist/router/Link.svelte

@@ -0,0 +1,27 @@
+<!--
+@component
+Represents a link that can be used to navigate within the application.
+-->
+
+<script module lang="ts">
+  import { type Snippet } from 'svelte';
+  import type { HTMLAnchorAttributes } from 'svelte/elements';
+
+  export type LinkProps = {
+    /**
+     * The content to display inside the link.
+     */
+    children?: Snippet;
+  } & HTMLAnchorAttributes;
+</script>
+
+
+<script lang="ts">
+  import { href } from './router.svelte';
+
+  const { children, ...attrs }: LinkProps = $props();
+</script>
+
+<a {...attrs} {@attach href(attrs.href)}>
+  {@render children?.()}
+</a>

package/dist/router/Link.svelte.d.ts

@@ -0,0 +1,12 @@
+import { type Snippet } from 'svelte';
+import type { HTMLAnchorAttributes } from 'svelte/elements';
+export type LinkProps = {
+    /**
+     * The content to display inside the link.
+     */
+    children?: Snippet;
+} & HTMLAnchorAttributes;
+/** Represents a link that can be used to navigate within the application. */
+declare const Link: import("svelte").Component<LinkProps, {}, "">;
+type Link = ReturnType<typeof Link>;
+export default Link;

package/dist/router/PageInfo.svelte

@@ -0,0 +1,23 @@
+<!--
+@component
+Provides a page title and icon for the current route.
+-->
+<script lang="ts" module>
+	export type PageInfoProps = {
+		title?: string;
+		icon?: string;
+	};
+</script>
+
+<script lang="ts">
+	import { getRouter } from '..';
+
+	const { title, icon }: PageInfoProps = $props();
+</script>
+
+<svelte:head>
+	<title>{title ?? getRouter().options.defaultTitle}</title>
+	{#if icon !== undefined}
+		<link rel="icon" href={icon} />
+	{/if}
+</svelte:head>

package/dist/router/PageInfo.svelte.d.ts

@@ -0,0 +1,8 @@
+export type PageInfoProps = {
+    title?: string;
+    icon?: string;
+};
+/** Provides a page title and icon for the current route. */
+declare const PageInfo: import("svelte").Component<PageInfoProps, {}, "">;
+type PageInfo = ReturnType<typeof PageInfo>;
+export default PageInfo;

package/dist/router/Route.svelte

@@ -0,0 +1,59 @@
+<!--
+@component
+The Route component is used to define a route in the application.
+It registers the route with the router when mounted and unregisters it when destroyed.
+Once registered, the route can be navigated to using the router's switchTo method.
+
+The children of this component make the content that will be displayed when the route is active.
+-->
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { RouteContainer } from './router.svelte';
+
+	export type RouteProps = {
+		path: string;
+		container?: RouteContainer;
+		children?: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	import { onDestroy, onMount } from 'svelte';
+	import {
+		type ApplicationRoute, getLayout, getRouteContainer, getRouter, type LayoutData, RoutePath
+	} from '..';
+
+  let {
+    path,
+		container,
+    children,
+  }: RouteProps = $props();
+
+	let router = getRouter();
+
+	let route : ApplicationRoute | undefined;
+
+  onMount(() => {
+		const layout = getLayout();
+
+		container ??= getRouteContainer();
+
+		const layoutPath = layout?.joinedPath ?? '';
+
+		const combinedPath = RoutePath.concatPaths(layoutPath, path);
+
+		route = {
+			path: RoutePath.fromString(combinedPath),
+			component: children,
+			layout: container.isRouter() ? undefined : container as LayoutData
+		};
+		container.registerRoute(route);
+  });
+
+	onDestroy(() => {
+		if (route) {
+			const container = getLayout() ?? router;
+			container.unregisterRoute(route);
+		}
+	})
+</script>

package/dist/router/Route.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from 'svelte';
+import type { RouteContainer } from './router.svelte';
+export type RouteProps = {
+    path: string;
+    container?: RouteContainer;
+    children?: Snippet;
+};
+/**
+ * The Route component is used to define a route in the application.
+ * It registers the route with the router when mounted and unregisters it when destroyed.
+ * Once registered, the route can be navigated to using the router's switchTo method.
+ *
+ * The children of this component make the content that will be displayed when the route is active.
+ */
+declare const Route: import("svelte").Component<RouteProps, {}, "">;
+type Route = ReturnType<typeof Route>;
+export default Route;