@snapstrat/switchboard 1.0.0

package/dist/router/Route404.svelte

@@ -0,0 +1,43 @@
+<svelte:options runes={true} />
+<script lang="ts" module>
+  import type { Snippet } from 'svelte';
+	import type { RouteContainer } from './router.svelte';
+  export type Route404Props = {
+    children: Snippet;
+		container?: RouteContainer;
+
+  }
+</script>
+
+<script lang="ts">
+  import { onDestroy, onMount } from 'svelte';
+	import { type ApplicationRoute, getLayout, getRouteContainer, getRouter, type LayoutData, RoutePath } from '..';
+
+  let { children, container }: Route404Props = $props();
+
+  let router = getRouter();
+
+  let route : ApplicationRoute | undefined;
+
+  onMount(() => {
+		const layout = getLayout();
+
+		container ??= getRouteContainer();
+
+		const layoutPath = layout?.joinedPath ?? '';
+
+    route = {
+      path: RoutePath.fromString(layoutPath, true),
+      component: children,
+			layout: container.isRouter() ? undefined : container as LayoutData
+		};
+    container.registerRoute404(route);
+  });
+
+  onDestroy(() => {
+    if (route) {
+      const container = getLayout() ?? router;
+      container.unregisterRoute(route);
+    }
+  })
+</script>

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

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { RouteContainer } from './router.svelte';
+export type Route404Props = {
+    children: Snippet;
+    container?: RouteContainer;
+};
+declare const Route404: import("svelte").Component<Route404Props, {}, "">;
+type Route404 = ReturnType<typeof Route404>;
+export default Route404;

package/dist/router/impl/index.d.ts

@@ -0,0 +1 @@
+export * from "./webRouter.svelte";

package/dist/router/impl/index.js

@@ -0,0 +1 @@
+export * from "./webRouter.svelte";

package/dist/router/impl/webRouter.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type Router, type RouterOptions } from '../..';
+/**
+ * Creates a {@link Router} that interfaces with the Web Browser's history API.
+ *
+ * @param options Options for the router, such as base path or initial route.
+ */
+export declare const createWebRouter: (options?: RouterOptions) => Router;

package/dist/router/impl/webRouter.svelte.js

@@ -0,0 +1,172 @@
+import { RouteParam, RoutePath, Route404Path, } from '../..';
+import { createSelector, parseWindowSearchParams } from '../internals/windowUtils';
+import { tick } from 'svelte';
+/**
+ * A router used for an entire application on the web.
+ */
+class WebRouter {
+    _routes = [];
+    _routes404 = [];
+    // routes are stored in reverse order for easier matching
+    // the most recently added routes are matched first
+    get routes() {
+        return this._routes.toReversed();
+    }
+    get routes404() {
+        return this._routes404.toReversed();
+    }
+    // this is undefined for a short time during initialization,
+    // after tick() it's always defined.
+    currentRoute = $state.raw(undefined);
+    options;
+    constructor(options) {
+        this.options = Object.freeze(options);
+        // we want to listen to popstate events to update the current route
+        // in this router
+        window.addEventListener('popstate', async (ev) => {
+            ev.preventDefault();
+            this.switchTo(window.location.pathname + window.location.search, {}, false);
+            await tick();
+            // restore focused element if we have one
+            const state = ev.state;
+            if (state?.focusedElement) {
+                const element = document.querySelector(state.focusedElement);
+                if (element) {
+                    element.focus();
+                }
+            }
+        });
+    }
+    get params() {
+        return this.currentRoute?.queryParams ?? {};
+    }
+    get queryParams() {
+        return this.currentRoute?.queryParams ?? {};
+    }
+    getRouteParam(name) {
+        return this.currentRoute.params[name];
+    }
+    getQueryParam(name) {
+        return this.currentRoute.queryParams[name];
+    }
+    refresh() {
+        this.switchTo(this.currentRoute.path, this.currentRoute.queryParams, true);
+    }
+    switchTo(path, queryParams = {}, pushNewState = true) {
+        const getQueryParam = queryParams instanceof Map ? (k) => queryParams.get(k) : (k) => queryParams[k];
+        const queryParamKeys = queryParams instanceof Map ? [...queryParams.keys()] : Object.keys(queryParams);
+        // create a url to easily manipulate the route params
+        const url = new URL(window.location.origin + path);
+        const route = this.getRoute(url.pathname);
+        // set the query params in the url to the new ones
+        for (const key of queryParamKeys) {
+            url.searchParams.set(key, getQueryParam(key));
+        }
+        path = url.pathname;
+        // create the new active route object
+        const params = this.createParams(path);
+        const queryParamsMap = {};
+        url.searchParams.forEach((value, key) => {
+            queryParamsMap[key] = value;
+        });
+        const selectedRoute = {
+            route,
+            params,
+            path: url.pathname,
+            queryParams: queryParamsMap
+        };
+        const state = {
+            focusedElement: document.activeElement
+                ? createSelector(document.activeElement)
+                : undefined,
+        };
+        // only used for changing focused element
+        window.history.replaceState(state, '');
+        if (pushNewState)
+            window.history.pushState({}, '', url);
+        this.currentRoute = selectedRoute;
+        return selectedRoute;
+    }
+    registerRoute(route) {
+        this._routes.push(route);
+    }
+    registerRoute404(route) {
+        this._routes404.push(route);
+        // switch to the new route if it's a 404 route and the current route is undefined
+        if (this.currentRoute?.route == undefined) {
+            this.switchTo(window.location.pathname, parseWindowSearchParams(), false);
+        }
+    }
+    /**
+     * Get a route by its path. Accounts for route parameters.
+     * @param path
+     */
+    getRoute(path) {
+        if (path == '/') {
+            return this.routes.find((route) => route.path.parts.length === 0) ?? this.getBase404();
+        }
+        // find the route that matches the path
+        const routes = this.findBestFit(path);
+        return routes ?? this.getClosest404(path);
+    }
+    findBestFit(path) {
+        return this.routes.find((route) => {
+            return route.path.matches(path);
+        });
+    }
+    getBase404() {
+        // return the global 404 route
+        return this.routes404.find((route) => route.path instanceof Route404Path && route.path.parts.length == 0);
+    }
+    getClosest404(path) {
+        // get the path minus the last segment
+        const splitPath = RoutePath.normalizePath(path).split('/').slice(0, -1);
+        for (let i = splitPath.length; i >= 0; i--) {
+            const subPath = '/' + splitPath.slice(0, i).join('/');
+            const route = this.routes404.find((route) => route.path.matches(subPath));
+            if (route) {
+                return route;
+            }
+        }
+        return this.getBase404();
+    }
+    // extract the route (not query) params from the path
+    createParams(path) {
+        if (path == '/')
+            return {};
+        const route = this.getRoute(path);
+        if (route == undefined) {
+            throw new Error(`Route not found for path: ${path}`);
+        }
+        const parts = RoutePath.normalizePath(path).split('/');
+        const params = {};
+        route.path.parts.forEach((part, index) => {
+            if (part instanceof RouteParam) {
+                params[part.name] = parts[index];
+            }
+        });
+        return params;
+    }
+    unregisterRoute(route) {
+        const toRemove = this._routes.indexOf(route);
+        if (toRemove == -1)
+            return;
+        if (this.currentRoute?.route == route) {
+            // switch to what will now be a 404 page if we're currently here
+            this.switchTo(this.currentRoute.path, parseWindowSearchParams(), false);
+        }
+        this._routes.splice(toRemove, 1);
+    }
+    getAllRoutes() {
+        return [...this.routes];
+    }
+    isRouter() { return true; }
+}
+/**
+ * Creates a {@link Router} that interfaces with the Web Browser's history API.
+ *
+ * @param options Options for the router, such as base path or initial route.
+ */
+export const createWebRouter = (options = {}) => {
+    return new WebRouter(options);
+};

package/dist/router/index.d.ts

@@ -0,0 +1,13 @@
+export { default as Link } from './Link.svelte';
+export * from './Link.svelte';
+export { default as BrowserRouter } from './BrowserRouter.svelte';
+export * from './BrowserRouter.svelte';
+export { default as Route404 } from './Route404.svelte';
+export * from './Route404.svelte';
+export { default as Route } from './Route.svelte';
+export * from './Route.svelte';
+export { default as PageInfo } from './PageInfo.svelte';
+export * from './PageInfo.svelte';
+export { default as Layout } from './Layout.svelte';
+export * from './Layout.svelte';
+export * from './router.svelte';

package/dist/router/index.js

@@ -0,0 +1,13 @@
+export { default as Link } from './Link.svelte';
+export * from './Link.svelte';
+export { default as BrowserRouter } from './BrowserRouter.svelte';
+export * from './BrowserRouter.svelte';
+export { default as Route404 } from './Route404.svelte';
+export * from './Route404.svelte';
+export { default as Route } from './Route.svelte';
+export * from './Route.svelte';
+export { default as PageInfo } from './PageInfo.svelte';
+export * from './PageInfo.svelte';
+export { default as Layout } from './Layout.svelte';
+export * from './Layout.svelte';
+export * from './router.svelte';

package/dist/router/internals/windowUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function parseWindowSearchParams(): Record<string, string>;
+export declare function createSelector(element: HTMLElement): string;

package/dist/router/internals/windowUtils.js

@@ -0,0 +1,29 @@
+export function parseWindowSearchParams() {
+    const params = {};
+    new URL(window.location.href).searchParams.forEach((value, key) => {
+        params[key] = value;
+    });
+    return params;
+}
+export function createSelector(element) {
+    const { tagName, id, className, parentNode } = element;
+    if (tagName === 'HTML')
+        return 'HTML';
+    let str = tagName;
+    str += (id !== '') ? `#${id}` : '';
+    if (className) {
+        const classes = className.split(/\s/);
+        for (let i = 0; i < classes.length; i++) {
+            str += `.${classes[i]}`;
+        }
+    }
+    let childIndex = 1;
+    for (let e = element; e.previousElementSibling; e = e.previousElementSibling) {
+        childIndex += 1;
+    }
+    str += `:nth-child(${childIndex})`;
+    if (!parentNode) {
+        return str;
+    }
+    return `${createSelector(parentNode)} > ${str}`;
+}

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

@@ -0,0 +1,178 @@
+import { type Snippet } from 'svelte';
+import type { Attachment } from 'svelte/attachments';
+export type RoutePart = string | RouteParam;
+export declare class RouteParam {
+    readonly name: string;
+    constructor(name: string);
+}
+/**
+ * A full path in the router.
+ * Can be created from a string, or from parts.
+ *
+ * Examples with created parts array:
+ * ```js
+ * RoutePath.fromString('/users/:userId')  // ['users', RouteParam('userId')]
+ * RoutePath.fromParts(['users', new RouteParam('userId')])  // ['users', RouteParam('userId')]
+ * RoutePath.create404()  // 404 route, no parts
+ * ```
+ */
+export declare class RoutePath {
+    readonly parts: readonly RoutePart[];
+    protected constructor(parts: readonly RoutePart[]);
+    static fromString(path: string, is404?: boolean): RoutePath;
+    static fromParts(parts: readonly RoutePart[]): RoutePath;
+    static create404(layout?: readonly RoutePart[]): RoutePath;
+    static readonly concatPaths: (base: string, ...rest: string[]) => string;
+    /**
+     * Normalize a path by removing leading and trailing slashes.
+     * @param path The path to normalize.
+     */
+    static readonly normalizePath: (path: string) => string;
+    readonly matches: (path: string) => boolean;
+}
+export declare class Route404Path extends RoutePath {
+    readonly parts: readonly RoutePart[];
+    constructor(parts: readonly RoutePart[]);
+}
+/**
+ * A route in the application. This is not necessarily the route that is currently active.
+ */
+export interface ApplicationRoute {
+    path: RoutePath;
+    layout?: LayoutData;
+    name?: string;
+    parents?: string[];
+    component?: Snippet;
+}
+export type RouterEvents = {
+    'route:afterSwitch': (oldRoute: ActiveRoute | undefined, newRoute: ActiveRoute) => void;
+};
+export type RouterOptions = Partial<{
+    /**
+     * The default page title to be used when no specific title is set for a route.
+     */
+    defaultTitle: string;
+    basePath: string;
+}>;
+export declare function defaultRouterOptions(): RouterOptions;
+/**
+ * A container for routes, either a router or a layout.
+ */
+export interface RouteContainer {
+    /**
+     * Create a route.
+     * @param route The route to register.
+     * @param layout The layout to register the route under.
+     */
+    registerRoute(route: ApplicationRoute, layout?: LayoutData): void;
+    /**
+     * Create a 404 route.
+     * @param route The route to register as a 404 route.
+     * @param layout The layout to register the route under.
+     */
+    registerRoute404(route: ApplicationRoute, layout?: LayoutData): void;
+    /**
+     * Remove a route
+     * @param route The route to unregister.
+     * @param layout The layout to unregister the route from.
+     */
+    unregisterRoute(route: ApplicationRoute, layout?: LayoutData): void;
+    /**
+     * Check if this route container is a router.
+     *
+     * @returns True if this is a router, false otherwise.
+     */
+    isRouter(): this is Router;
+}
+/**
+ * A router used to switch between routes in an application.
+ */
+export interface Router extends RouteContainer {
+    readonly options: RouterOptions;
+    /** Params specified in the route with : syntax, like /users/:userId */
+    params: RouteParams;
+    /** Query params specified after the route with ?, like /users/1234?showFullName=true */
+    queryParams: RouteParams;
+    /**
+     * Switch to a route.
+     * @param path
+     * @param queryParams
+     * @param pushNewState
+     */
+    switchTo(path: string, queryParams?: Record<string, string> | RouteParams, pushNewState?: boolean): ActiveRoute;
+    /**
+     * Get the current route.
+     */
+    currentRoute: ActiveRoute;
+    getRoute(path: string): ApplicationRoute;
+    /**
+     * Get all routes, including 404 routes.
+     */
+    getAllRoutes(): ApplicationRoute[];
+    createParams(path: string): RouteParams;
+    /**
+     * A quick refresh will not push a new state to the browser's history.
+     * @param quick
+     */
+    refresh(quick?: boolean): void;
+    /**
+     * Get a route parameter by name from the current route.
+     * @param name
+     */
+    getRouteParam(name: string): string;
+    /**
+     * Get a query parameter by name from the current route.
+     * @param name
+     */
+    getQueryParam(name: string): string | undefined;
+}
+export interface ActiveRoute {
+    /**
+     * The route object that is currently active.
+     */
+    route: ApplicationRoute;
+    /**
+     * Note: this may differ from route.path if the route is a 404 route.
+     */
+    path: string;
+    /** Params specified in the route with : syntax, like /users/:userId */
+    params: RouteParams;
+    /** Query params specified after the route with ?, like /users/1234?showFullName=true */
+    queryParams: RouteParams;
+}
+export type RouteParams = {
+    [key: string]: string;
+};
+export declare const ROUTER_CONTEXT_KEY = "switchboard::router";
+export declare const LAYOUT_CONTEXT_KEY = "switchboard::layout";
+export declare const ROUTE_NOT_FOUND_KEY = "__switchboard__404";
+export type LayoutSnippet = Snippet<[Snippet]>;
+export interface LayoutData extends RouteContainer {
+    path?: string;
+    parent?: LayoutData;
+    canonicalParent?: LayoutData;
+    renderer: LayoutSnippet;
+    notFoundRoute?: ApplicationRoute;
+    joinedPath: string;
+}
+export declare function getLayout(): LayoutData | undefined;
+export declare function setLayoutContext(layout: LayoutData | undefined): void;
+export declare function getRouter<T extends Router = Router>(): T;
+export declare function getRouteParams(): RouteParams;
+export declare function getQueryParams(): RouteParams;
+export declare function setRouterContext(router: Router): void;
+/**
+ * Gets the nearest route container, either a layout or the router.
+ */
+export declare function getRouteContainer(): RouteContainer;
+/**
+ * Create an attachment that sets the href of an anchor element
+ * and switches to the route when clicked.
+ * This is useful for creating links that work with the router, and won't cause a refresh when clicked.
+ * @param href The href to set on the anchor element.
+ *
+ * @see Link
+ */
+export declare const href: (href: string) => Attachment<HTMLAnchorElement>;
+export declare const getAllLayouts: (layout?: LayoutData) => LayoutData[];
+export declare const getAllCanonicalLayouts: (layout?: LayoutData) => LayoutData[];

package/dist/router/router.svelte.js

@@ -0,0 +1,167 @@
+import { getContext, hasContext, setContext } from 'svelte';
+// A dynamic route parameter.
+export class RouteParam {
+    name;
+    constructor(name) {
+        this.name = name;
+    }
+}
+/**
+ * A full path in the router.
+ * Can be created from a string, or from parts.
+ *
+ * Examples with created parts array:
+ * ```js
+ * RoutePath.fromString('/users/:userId')  // ['users', RouteParam('userId')]
+ * RoutePath.fromParts(['users', new RouteParam('userId')])  // ['users', RouteParam('userId')]
+ * RoutePath.create404()  // 404 route, no parts
+ * ```
+ */
+export class RoutePath {
+    parts;
+    constructor(parts) {
+        this.parts = parts;
+    }
+    static fromString(path, is404 = false) {
+        const ctor = is404 ? Route404Path : RoutePath;
+        if (path == '/' || path === '') {
+            return new ctor([]);
+        }
+        path = RoutePath.normalizePath(path);
+        return new ctor(path.split('/').map((part) => {
+            if (part.startsWith(':')) {
+                return new RouteParam(part.substring(1));
+            }
+            else {
+                return part;
+            }
+        }));
+    }
+    static fromParts(parts) {
+        return new RoutePath(parts);
+    }
+    static create404(layout = []) {
+        return new Route404Path(layout);
+    }
+    static concatPaths = (base, ...rest) => {
+        base = RoutePath.normalizePath(base);
+        const normalizedRest = rest.map(p => RoutePath.normalizePath(p));
+        const restStr = normalizedRest.join('/');
+        if (base === '') {
+            return RoutePath.normalizePath(restStr);
+        }
+        return RoutePath.normalizePath([...base.split("/"), ...restStr.split("/")].join("/"));
+    };
+    /**
+     * Normalize a path by removing leading and trailing slashes.
+     * @param path The path to normalize.
+     */
+    static normalizePath = (path) => {
+        if (path.startsWith('/')) {
+            path = path.substring(1); // remove leading slash
+        }
+        if (path.endsWith('/')) {
+            path = path.slice(0, -1); // remove trailing slash
+        }
+        return path;
+    };
+    matches = (path) => {
+        const parts = RoutePath.normalizePath(path).split('/');
+        if (parts.length != this.parts.length)
+            return false;
+        return this.parts.every((part, index) => {
+            if (part instanceof RouteParam)
+                return true;
+            return part == parts[index];
+        });
+    };
+}
+export class Route404Path extends RoutePath {
+    parts;
+    constructor(parts) {
+        super(parts);
+        this.parts = parts;
+    }
+}
+export function defaultRouterOptions() {
+    return {
+        defaultTitle: 'App',
+    };
+}
+export const ROUTER_CONTEXT_KEY = 'switchboard::router';
+export const LAYOUT_CONTEXT_KEY = 'switchboard::layout';
+export const ROUTE_NOT_FOUND_KEY = '__switchboard__404';
+export function getLayout() {
+    return hasContext(LAYOUT_CONTEXT_KEY)
+        ? getContext(LAYOUT_CONTEXT_KEY)
+        : undefined;
+}
+export function setLayoutContext(layout) {
+    // set the layout in the context
+    setContext(LAYOUT_CONTEXT_KEY, layout);
+}
+export function getRouter() {
+    return getContext(ROUTER_CONTEXT_KEY);
+}
+export function getRouteParams() {
+    const router = getRouter();
+    return router.currentRoute.params;
+}
+export function getQueryParams() {
+    const router = getRouter();
+    return router.currentRoute.queryParams;
+}
+export function setRouterContext(router) {
+    // set the router in the context
+    setContext(ROUTER_CONTEXT_KEY, router);
+}
+/**
+ * Gets the nearest route container, either a layout or the router.
+ */
+export function getRouteContainer() {
+    return getLayout() ?? getRouter();
+}
+/**
+ * Create an attachment that sets the href of an anchor element
+ * and switches to the route when clicked.
+ * This is useful for creating links that work with the router, and won't cause a refresh when clicked.
+ * @param href The href to set on the anchor element.
+ *
+ * @see Link
+ */
+export const href = (href) => {
+    const router = getRouter();
+    return (element) => {
+        const handler = () => {
+            router.switchTo(href);
+        };
+        element.href = href;
+        element.addEventListener("click", handler);
+        element.addEventListener("keydown", handler);
+        return () => {
+            element.href = "";
+            element.removeEventListener("click", handler);
+            element.removeEventListener("keydown", handler);
+        };
+    };
+};
+export const getAllLayouts = (layout) => {
+    const list = [];
+    if (!layout)
+        return list;
+    while (layout) {
+        list.push(layout);
+        layout = layout.parent;
+    }
+    return list.reverse();
+};
+export const getAllCanonicalLayouts = (layout) => {
+    const list = [];
+    if (!layout)
+        return list;
+    while (layout) {
+        list.push(layout);
+        layout = layout.canonicalParent;
+    }
+    return list.reverse();
+};