svelte-spa-history-router 3.0.0-next.1 → 3.0.0

package/README.md

@@ -1,22 +1,21 @@
 # svelte-spa-history-router
 
-History base router for [Svelte](https://svelte.dev/) SPA (Single Page Application).
+A history-based router for [Svelte](https://svelte.dev/) Single Page Applications (SPAs).
 
 > [!TIP]
-> The offcial routing library of Svelte is [SvelteKit](https://svelte.dev/docs/kit/introduction). This library is intented to be used for small/simple project.
-
+> Svelte's official routing library is [SvelteKit](https://svelte.dev/docs/kit/introduction). This library is designed for small or simple projects.
 
 ## Features
 
-- History-base routing
-- path matching and path variable capturing by regular expression
-- resolver (for dynamic routing, code-splitting, data preloading, etc...)
+- History-Based Routing
+- Path matching and Variable Capture using regular expressions
+- Resolver for dynamic routing, code splitting, data preloading, etc.
 
-## *Not* supported features
+## Features *not* supported
 
-- Hash-base routing
+- Hash-based Routing
 - Nested router
-- SSR (Server Side Rendering)
+- Server-Side Rendering (SSR)
 
 ## Install
 
@@ -28,7 +27,7 @@ $ yarn add svelte-spa-history-router
 
 ## Usage
 
-Import `Router` and put into your main component (typically App.svelte).
+Import `Router` and include it in your main component (typically App.svelte).
 
 For example:
 
@@ -51,59 +50,76 @@ For example:
 <Router {routes}/>
 ```
 
-* `Routes` require a `routes` parameter.
-* `routes` is a list of route objects. route object has `path` property, and either `component` or `resolver` property.
+* `Router` requires the `routes` parameter.
+* `routes` is a list of route objects. Each route object must have a `path` property, and either a `component` or `resolver` property.
 
   * `path` can be a regular expression. `^` and `$` are automatically added when matching.
-  * `component` is a Svelte component. there are no specific requirements for component.
-  * `resolver` is a function to determine component dynamically.
+  * `component` is a Svelte component. There are no specific requirements for the component.
+  * `resolver` is a function to return a dynamic component and return props of the type expected by the component.
 
 * Matching is simply performed in the order defined by `routes`.
 
 ### Path variable
 
-Matched paramaters are passed to component as `params` property.
+For routes that do not use a resolver, matched parameters are passed to the component via the `params` prop.
 
 For example:
 
 ```html
-# Article.svelte
+# App.svelte
+<script>
+  import { Router } from "svelte-spa-history-router";
+  import ItemPage from "./ItemPage.svelte";
+
+  const routes = [
+    { path: "/items/(?<itemId>\\d+)", component: ItemPage },
+  ];
+</script>
+<Router {routes}/>
+```
+
+```html
+# ItemPage.svelte
 
 <script lang="ts">
-  let { params }: { params: { postId: string } = $props();
+  let { params }: { params: { itemId: string } } = $props();
 
-  const postId = $derived(parseInt(params.postId));
+  const itemId = $derived(parseInt(params.itemId));
 </script>
 <div>
-  { postId }
+  { itemId }
 </div>
 ```
 
 ### Navigation methods
 
-To navigate another page, `link` and `push` are available.
+To navigate to another page, `link` and `push` are available.
 
-* `link` is used with a `a` tag like below
+* `link` turns an `<a>` tag into a spa navigation link. For example:
 
 ```html
-import { link } from 'svelte-spa-history-router';
+<script>
+  import { link } from 'svelte-spa-history-router';
+</script>
 
 <a use:link href="/">Home</a>
 ```
 
-* `push` is used to navigate programatically
+* `push` navigates to the given path programatically.
 
 ```html
-import { push } from 'svelte-spa-history-router';
+<script>
+  import { push } from 'svelte-spa-history-router';
+<script>
 
 <button onclick={ () => push('/') }>Go to Home</button>
 ```
 
 ### resolver
 
-Resolver is a mechanism to dynamically determine component and can be used in multiple use cases.
+A resolver is a mechanism for dynamically determining which component to render. It can be used for various purposes, such as:
 
-Example: code spliting (dynamic import)
+Example: code splitting (dynamic import)
 
 ```html
 <script>
@@ -141,6 +157,9 @@ Example: dynamic routing and pass value to component props.
 <Router {routes}/>
 ```
 
+> [!TIP]
+> This routing mechanism allows preloading data before rendering the component, minimizing layout flicker and improving perceived performance. While skeleton screens are a common modern pattern, this approach can simplify state handling in simple apps.
+
 Example: guard
 
 ```html
@@ -167,9 +186,23 @@ Example: guard
 <Router {routes}/>
 ```
 
+A resolver must return one of the following types:
+
+```typescript
+| Component
+| { component: Component, props: ComponentProps }
+| Redirection // return value of `redirect()`
+| Promise<
+   | Component
+   | { component: Component, props: ComponentProps }
+   | Redirection
+   | { default: Component } // return value of `import()`
+  >
+```
+
 (Added in v2.0.0)
 
-(Changed resolver interface in v3.0.0-next.0)
+(Changed resolver interface in v3.0.0-next.1)
 
 ### currentURL()
 
@@ -186,7 +219,7 @@ state to detect URL changes (including query string or hash)
 
 (Added in v2.1.0)
 
-(Replaced to svelte5 `$state()` in v3.0.0-next.0)
+(Replaced with Svelte5's `$state()` in v3.0.0-next.1)
 
 ### Typing
 
@@ -204,7 +237,7 @@ svelte-spa-history-router provides `Route` type to check combination of componen
   const routes: [
     Route<typeof Top>,
     Route<typeof BlogPost | typeof NotFound>,
-  ]: [
+  ] = [
     { path: "/", component: Top },
     {
       path: "/blog/posts/(?<slug>.*)",
@@ -220,16 +253,17 @@ svelte-spa-history-router provides `Route` type to check combination of componen
     },
   ];
 </script>
+```
 
-(Added in v3.0.0-next.0)
+(Added in v3.0.0-next.1)
 
 ### Full example:
 
-[example](https://github.com/ykrods/svelte-spa-history-router/tree/master/example)
+[example](https://github.com/ykrods/svelte-spa-history-router/tree/master/src)
 
 ## ChangeLog
 
-### 3.0.0-next.0
+### 3.0.0-next.1
 
 * *[Breaking change]* Drop Svelte4 support
 
@@ -286,9 +320,9 @@ MIT License.
 
 ## Appendix
 
-Generally, history-base router requires server-side routing so that user can open the direct link or reload.
+A history-based router generally requires server-side routing to support direct links or page reloads.
 
-For example, Nginx excerpt configuration is like bellow.
+For example, the following nginx configuration allows proper routing:
 
 ```
 location / {
@@ -296,10 +330,10 @@ location / {
 }
 ```
 
-If you consider to use firebase hosting for your application, [rewrite](https://firebase.google.com/docs/hosting/full-config#rewrites) may be useful.
+If you are considering using firebase hosting for your application, [rewrite](https://firebase.google.com/docs/hosting/full-config#rewrites) may be useful.
 
 ## Inspired
 
 svelte-spa-history-router is inspired by [svelte-spa-router](https://github.com/ItalyPaleAle/svelte-spa-router) and [Svelte Router SPA](https://github.com/jorgegorka/svelte-router).
 
-If you don't need both history-base and regular expression support, I reccommend these powerful routers.
+If you don't need support for both history-based routing and regular expressions, I recommend these powerful routers.

package/dist/Router.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Component } from "svelte";
+import type { Route } from "./types";
+type $$ComponentProps = {
+    routes: Route<any>[];
+};
+/**
+ * Router component
+ *
+ * @example
+ * <script>
+ * import { Router } from "svelte-spa-history-router";
+ *
+ * import Top from "./Top.svelte"
+ * import NotFound from "./NotFound.svelte"
+ *
+ * const routes = [
+ *   { path: "/", component: Top },
+ *   { path: "/posts/(?<postId>.*)", resolver: () => import("./Article.svelte") },
+ *   { path: ".*", component: NotFound },
+ * ];
+ * </script>
+ * <Router {routes}/>
+ */
+declare const Router: Component<$$ComponentProps, {}, "">;
+type Router = ReturnType<typeof Router>;
+export default Router;

package/dist/currentURL.d.ts

@@ -0,0 +1 @@
+export declare function currentURL(): URL;

package/{src/currentURL.ts → dist/currentURL.js}

@@ -1,9 +1,6 @@
 // https://svelte.dev/docs/svelte/compiler-warnings#state_referenced_locally
 // https://svelte.dev/docs/svelte/$state#Passing-state-into-functions
-
-import { getSpaContext } from "./spa-context"
-
-
-export function currentURL(): URL {
-  return getSpaContext().currentURL();
+import { getSpaContext } from "./spa-context";
+export function currentURL() {
+    return getSpaContext().currentURL();
 }

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { Route } from "./types";
+export { default as Router } from "./Router.svelte";
+export { link } from "./link";
+export { push } from "./push";
+export { redirect } from "./redirect";
+export { currentURL } from "./currentURL";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default as Router } from "./Router.svelte";
+export { link } from "./link";
+export { push } from "./push";
+export { redirect } from "./redirect";
+export { currentURL } from "./currentURL";

package/dist/link.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Svelte action to make `<a>` work as navigation of svelte-spa-history-router
+ *
+ * @param node - target `<a>`
+ *
+ * @example
+ *
+ *   <a use:link href="/">top</a>
+ */
+export declare function link(node: HTMLAnchorElement): {
+    destroy(): void;
+};

package/dist/link.js

@@ -0,0 +1,25 @@
+import { push } from "./push";
+/**
+ * Svelte action to make `<a>` work as navigation of svelte-spa-history-router
+ *
+ * @param node - target `<a>`
+ *
+ * @example
+ *
+ *   <a use:link href="/">top</a>
+ */
+export function link(node) {
+    function onClick(event) {
+        event.preventDefault();
+        var href = node.getAttribute("href");
+        if (href) {
+            push(href);
+        }
+    }
+    node.addEventListener("click", onClick);
+    return {
+        destroy: function () {
+            node.removeEventListener("click", onClick);
+        },
+    };
+}

package/dist/push.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Navigate to next page programmatically
+ *
+ * @example
+ *
+ *   <button onclick={ () => push(`posts/${id}`) }>next</button>
+ */
+export declare function push(next: string): void;

package/dist/push.js

@@ -0,0 +1,12 @@
+import * as SpaEvent from "./spa-event";
+/**
+ * Navigate to next page programmatically
+ *
+ * @example
+ *
+ *   <button onclick={ () => push(`posts/${id}`) }>next</button>
+ */
+export function push(next) {
+    var evt = new CustomEvent(SpaEvent.NAVIGATE, { detail: { next: next } });
+    window.dispatchEvent(evt);
+}

package/dist/redirect.d.ts

@@ -0,0 +1,6 @@
+import type { Redirection } from "./types";
+/**
+ * This is special function used in resolvers.
+ * Normally, you use `push()` to change the url.
+ */
+export declare function redirect(to: string): Redirection;

package/dist/redirect.js

@@ -0,0 +1,7 @@
+/**
+ * This is special function used in resolvers.
+ * Normally, you use `push()` to change the url.
+ */
+export function redirect(to) {
+    return { redirect: to };
+}

package/dist/spa-context.d.ts

@@ -0,0 +1,3 @@
+import type { SpaContext } from "./types";
+export declare function setSpaContext(ctx: SpaContext): void;
+export declare function getSpaContext(): SpaContext;

package/dist/spa-context.js

@@ -0,0 +1,8 @@
+import { setContext, getContext } from "svelte";
+var key = Symbol("svelte-spa-history-router");
+export function setSpaContext(ctx) {
+    setContext(key, ctx);
+}
+export function getSpaContext() {
+    return getContext(key);
+}

package/dist/spa-event.d.ts

@@ -0,0 +1 @@
+export declare const NAVIGATE = "spa-navigate";

package/dist/spa-event.js

@@ -0,0 +1 @@
+export var NAVIGATE = "spa-navigate";

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import type { Component, ComponentProps } from "svelte";
+import * as SpaEvent from "./spa-event";
+export type NavigationEvent = CustomEvent<{
+    next: string;
+}>;
+declare global {
+    interface WindowEventMap {
+        [SpaEvent.NAVIGATE]: NavigationEvent;
+    }
+}
+export interface Redirection {
+    redirect: string;
+}
+export interface Destination<T extends Component<any>> {
+    component: T;
+    props: ComponentProps<T>;
+}
+type DestMap<T extends Component<any>> = T extends unknown ? Destination<T> : never;
+export type Route<T extends Component<any> = Component> = {
+    path: string;
+    component?: T;
+    resolver?: (params: Record<string, string>) => DestMap<T> | T | Redirection | Promise<DestMap<T> | T | Redirection | {
+        default: T;
+    }>;
+};
+export interface SpaContext {
+    currentURL(): URL;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,8 @@
+export {};
+/*
+export type ResolverArgs = {
+  path: string,
+  params: RouteParams,
+  props: RouteProps,
+}
+*/

package/package.json

@@ -1,17 +1,21 @@
 {
   "name": "svelte-spa-history-router",
-  "version": "3.0.0-next.1",
+  "version": "3.0.0",
   "description": "History base router for Svelte SPA",
   "type": "module",
-  "main": "src/index.ts",
-  "svelte": "src/index.ts",
+  "files": [
+    "dist"
+  ],
+  "svelte": "./dist/index.ts",
   "exports": {
     ".": {
-      "svelte": "./src/index.ts"
+      "svelte": "./dist/index.ts",
+      "types": "./dist/index.d.ts"
     }
   },
   "scripts": {
     "dev": "vite",
+    "build": "svelte-package",
     "test": "playwright test",
     "check": "svelte-check --tsconfig ./tsconfig.app.json && tsc -p tsconfig.node.json"
   },
@@ -19,14 +23,15 @@
     "svelte": ">5.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "1.49.1",
+    "@playwright/test": "1.52.0",
+    "@sveltejs/package": "2.3.11",
     "@sveltejs/vite-plugin-svelte": "5.0.3",
     "@tsconfig/svelte": "5.0.4",
-    "playwright": "1.49.1",
-    "svelte": "5.16.0",
-    "svelte-check": "4.1.1",
-    "typescript": "5.7.2",
-    "vite": "6.0.6"
+    "playwright": "1.52.0",
+    "svelte": "5.28.2",
+    "svelte-check": "4.1.6",
+    "typescript": "5.8.3",
+    "vite": "6.3.4"
   },
   "author": "ykrods",
   "license": "MIT",

package/.vscode/extensions.json

@@ -1,3 +0,0 @@
-{
-  "recommendations": ["svelte.svelte-vscode"]
-}

package/example/App.svelte

@@ -1,117 +0,0 @@
-<script lang="ts">
-  import type { Route } from "svelte-spa-history-router"
-  import { Router, link, push, redirect } from "svelte-spa-history-router"
-
-  import type Admin from "./pages/Admin.svelte"
-  import type Blog from "./pages/Blog.svelte"
-  import type BlogPost from "./pages/BlogPost.svelte"
-  import type Query from "./pages/Query.svelte"
-
-  import IntParam from "./pages/IntParam.svelte"
-  import Message from "./pages/Message.svelte"
-  import NotFound from "./pages/NotFound.svelte"
-  import Params from "./pages/Params.svelte"
-  import Top from "./pages/Top.svelte"
-
-  import { getArticle } from "./lib/getArticle"
-
-
-  const routes: [
-    Route,
-    Route<typeof Params>,
-    Route<typeof IntParam>,
-    Route<typeof IntParam | typeof Message>,
-    Route<typeof Blog>,
-    Route<typeof BlogPost | typeof NotFound>,
-    Route<typeof Admin>,
-    Route<typeof Query>,
-    Route<typeof NotFound>,
-  ] = [
-    { path: "/", component: Top },
-    // path variable via params
-    { path: "/params/(?<slug>.*)", component: Params },
-    // typed props
-    {
-      path: "/int-param/(?<num>\\d+)",
-      resolver: (params: Record<"num", string>) => ({
-        component: IntParam,
-        props: { num: parseInt(params.num) }
-      }),
-    },
-    {
-      path: "/conditional/(?<arg>.+)",
-      resolver: (params: Record<"arg", string>) => {
-        const arg = parseInt(params.arg)
-        if (!Number.isNaN(arg)) {
-          return { component: IntParam, props: { num: arg }}
-        }
-        return {
-          component: Message,
-          props: { message: `Unexpected param: ${params.arg}` }
-        }
-      }
-    },
-    // spliting
-    {
-      path: "/blog",
-      resolver: () => import("./pages/Blog.svelte"),
-    },
-    // async resolver with props
-    // path variable with slash
-    // prefetch
-    // spliting
-    // return component
-    {
-      path: "/blog/posts/(?<slug>.*)",
-      resolver: async (params: Record<"slug", string>) => {
-        const article = await getArticle(params.slug);
-        if (article) {
-          const component = (await import("./pages/BlogPost.svelte")).default;
-          return { component, props: { article } }
-        } else {
-          return NotFound;
-        }
-      },
-    },
-    // guard
-    // redirect
-    {
-      path: "/admin",
-      resolver: () => {
-        if (user === "admin") {
-          return import("./pages/Admin.svelte");
-        } else {
-          return redirect("/");
-        }
-      },
-    },
-    {
-      path: "/query",
-      resolver: () => import("./pages/Query.svelte")
-    },
-    { path: ".*", component: NotFound },
-  ]
-
-  let user = $state("anonymous");
-</script>
-<main>
-  <header>
-    <nav>
-      <a use:link href="/">Top</a> |
-      <a use:link href="/params/foo/bar">params</a> |
-      <a use:link href="/int-param/3">int param</a> |
-      <a use:link href="/conditional/1">conditional (1)</a> |
-      <a use:link href="/conditional/a">conditional (a)</a> |
-      <a use:link href="/blog">blog</a> |
-      <a use:link href="/admin">admin</a> |
-      <a use:link href="/query">query</a> |
-
-      {#if user === "anonymous"}
-        <button id="login" onclick={() => { user = "admin" }}>Login</button>
-      {:else}
-        user: { user } <button onclick={() => { user = "anonymous"; push("/"); }}>Logout</button>
-      {/if}
-    </nav>
-  </header>
-  <Router {routes} />
-</main>

package/example/index.html

@@ -1,13 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Vite + Svelte + TS</title>
-  </head>
-  <body>
-    <div id="app"></div>
-    <script type="module" src="/main.ts"></script>
-  </body>
-</html>

package/example/lib/getArticle.ts

@@ -1,13 +0,0 @@
-import type { Article } from "../types"
-
-import { getArticles } from "./getArticles"
-
-
-const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
-
-
-export async function getArticle(id: string): Promise<Article | undefined> {
-  await sleep(50);
-  const articles = await getArticles();
-  return articles.find(a => a.id === id);
-}

package/example/lib/getArticles.ts

@@ -1,43 +0,0 @@
-import type { Article } from "../types"
-
-
-const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
-
-
-const articles: Article[] = [
-  {
-    id: '2024/04/01/test-fragment',
-    title: 'test fragment',
-    date: "2024-04-01",
-    html: `<a id="top" href="#bottom">to bottom</a>
-<div style="height:800px">spacer</div>
-<a id="bottom" href="#top">to top</a>`,
-  },
-  {
-    id: '2024/03/01/baz',
-    title: 'baz',
-    date: "2024-03-01",
-    html: `<p>baz!</p>`,
-    prev: '2024/02/01/bar',
-  },
-  {
-    id: '2024/02/01/bar',
-    title: 'bar',
-    date: "2024-02-01",
-    html: `<p>bar!</p>`,
-    next: '2024/03/01/baz',
-    prev: '2024/01/01/foo',
-  },
-  {
-    id: '2024/01/01/foo',
-    title: 'foo',
-    date: "2024-01-01",
-    html: `<p>foo!</p>`,
-    next: '2024/02/01/bar',
-  },
-];
-
-export async function getArticles(): Promise<Article[]> {
-  await sleep(100);
-  return articles;
-}