svelte-spa-history-router 2.2.0 → 3.0.0-next.2

package/.vscode/extensions.json

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

package/README.md

@@ -3,7 +3,7 @@
 History base router for [Svelte](https://svelte.dev/) SPA (Single Page Application).
 
 > [!TIP]
-> The offcial routing library of Svelte is [SvelteKit](https://svelte.dev/docs/kit/introduction). This library is intented to be used for small project.
+> 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.
 
 
 ## Features
@@ -52,17 +52,17 @@ For example:
 ```
 
 * `Routes` require a `routes` parameter.
-* `routes` is a list of route objects. route object has `path`, `component`, and `resolver` properties.
+* `routes` is a list of route objects. route object has `path` property, and either `component` or `resolver` property.
 
   * `path` can be a regular expression. `^` and `$` are automatically added when matching.
-  * `component` is a SvelteComponent. there are no specific requirements for component.
-  * `resolver` is a function to determine component dynamically (optional).
+  * `component` is a Svelte component. there are no specific requirements for component.
+  * `resolver` is a function to determine component dynamically.
 
 * Matching is simply performed in the order defined by `routes`.
 
-### routeParams
+### Path variable
 
-Matched paramaters is passed to component as `params` property.
+Matched paramaters are passed to component as `params` property.
 
 For example:
 
@@ -70,7 +70,7 @@ For example:
 # Article.svelte
 
 <script lang="ts">
-  let { params } = $props();
+  let { params }: { params: { postId: string } = $props();
 
   const postId = $derived(parseInt(params.postId));
 </script>
@@ -79,25 +79,11 @@ For example:
 </div>
 ```
 
-[Additional] For svelte4, `routeParams` is a store to contain matched value to current route.
-
-```html
-# Article.svelte
-
-<script>
-  import { routeParams } from 'svelte-spa-history-router';
-</script>
-
-<div class="article">
-  postId: {$routeParams.postId}
-</div>
-```
-
 ### Navigation methods
 
 To navigate another page, `link` and `push` are available.
 
-* `link` used with a `a` tag like below
+* `link` is used with a `a` tag like below
 
 ```html
 import { link } from 'svelte-spa-history-router';
@@ -105,12 +91,12 @@ import { link } from 'svelte-spa-history-router';
 <a use:link href="/">Home</a>
 ```
 
-* `push` used to navigate programatically
+* `push` is used to navigate programatically
 
 ```html
 import { push } from 'svelte-spa-history-router';
 
-<button on:click={ () => push('/') }>Go to Home</button>
+<button onclick={ () => push('/') }>Go to Home</button>
 ```
 
 ### resolver
@@ -133,18 +119,16 @@ Example: code spliting (dynamic import)
 Example: dynamic routing and pass value to component props.
 
 ```html
-<script>
+<script lang="ts">
   import { Router } from 'svelte-spa-history-router';
 
   import Article from "./Article.svelte";
   import NotFound from "./NotFound.svelte";
 
-  async function prefetchArticle({ params, props }) {
+  async function prefetchArticle(params: Record<string, string>) {
     const article = await getArticle(params.postId);
     if (article) {
-      // pass value to component props
-      props.article = article;
-      return Article;
+      return { component: Article, props: { article } };
     } else {
       return NotFound;
     }
@@ -160,13 +144,16 @@ Example: dynamic routing and pass value to component props.
 Example: guard
 
 ```html
-<script>
+<script lang="ts">
   import { Router, redirect } from 'svelte-spa-history-router';
 
   import Admin from "./Admin.svelte";
 
-  function adminGuard(route) {
-    if (!isAdmin($user)) {
+
+  let user: User = $state()
+
+  function adminGuard() {
+    if (!isAdmin(user)) {
       return redirect("/");
     }
     return Admin;
@@ -182,20 +169,60 @@ Example: guard
 
 (Added in v2.0.0)
 
-### currentURL
+(Changed resolver interface in v3.0.0-next.1)
+
+### currentURL()
 
-store to detect URL changes (including query string or hash)
+state to detect URL changes (including query string or hash)
 
 ```html
 <script>
   import { currentURL } from "svelte-spa-history-router";
 
-  $: name = $currentURL.searchParams.get("name") || 'unknown';
+  let name = $derived(currentURL().searchParams.get("name") ?? "unknown");
 </script>
 <div>{ name }</div>
 ```
 
-(Added in 2.1.0)
+(Added in v2.1.0)
+
+(Replaced to svelte5 `$state()` in v3.0.0-next.1)
+
+### Typing
+
+svelte-spa-history-router provides `Route` type to check combination of component and props.
+
+```typescript
+<script lang="ts">
+  import type { Route } from "svelte-spa-history-router"
+
+  // BlogPost requires article property
+  import type BlogPost from "./pages/BlogPost.svelte"
+
+  import Top from "./pages/Top.svelte"
+
+  const routes: [
+    Route<typeof Top>,
+    Route<typeof BlogPost | typeof NotFound>,
+  ]: [
+    { path: "/", component: Top },
+    {
+      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;
+        }
+      },
+    },
+  ];
+</script>
+```
+
+(Added in v3.0.0-next.1)
 
 ### Full example:
 
@@ -203,6 +230,15 @@ store to detect URL changes (including query string or hash)
 
 ## ChangeLog
 
+### 3.0.0-next.1
+
+* *[Breaking change]* Drop Svelte4 support
+
+  * Remove stores of `routeParams` and `currentURL`
+
+* *[Breaking change]* Change resolver interface
+* Add `currentURL()` which is rewriten to use `$state()`
+
 ### 2.2.0
 
 * Support Svelte5

package/example/App.svelte

@@ -0,0 +1,117 @@
+<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/{examples/app-svelte5 → example}/index.html

@@ -1,14 +1,13 @@
-<!DOCTYPE html>
+<!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</title>
-    <!--app-head-->
+    <title>Vite + Svelte + TS</title>
   </head>
   <body>
-    <div id="app"><!--app-html--></div>
-    <script type="module" src="/src/main.js"></script>
+    <div id="app"></div>
+    <script type="module" src="/main.ts"></script>
   </body>
 </html>

package/example/lib/getArticle.ts

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,43 @@
+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;
+}

package/example/main.ts

@@ -0,0 +1,8 @@
+import { mount } from 'svelte'
+import App from './App.svelte'
+
+const app = mount(App, {
+  target: document.getElementById('app')!,
+})
+
+export default app

package/{examples/app-svelte5/src → example}/pages/Admin.svelte

@@ -3,4 +3,5 @@
 </svelte:head>
 <main class="admin">
   <h1>Admin</h1>
+  <p>admin page</p>
 </main>

package/example/pages/Blog.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import { link } from "svelte-spa-history-router"
+
+  import { getArticles } from "../lib/getArticles"
+</script>
+<svelte:head>
+  <title>Blog</title>
+</svelte:head>
+<main class="blog">
+  {#await getArticles() then articles}
+  <h1>Blog</h1>
+  <ul>
+      {#each articles as article}
+        <li>{ article.date } - <a use:link href={`/blog/posts/${article.id}`}>{ article.title }</a></li>
+      {/each}
+      <li>2024-01-01 - <a use:link href="/blog/posts/2024/01/01/deleted">deleted</a></li>
+  </ul>
+  {/await}
+</main>

package/example/pages/BlogPost.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+  import type { Article } from "../types"
+
+  import { link } from "svelte-spa-history-router"
+
+  let { article }: { article: Article } = $props()
+</script>
+<svelte:head>
+  <title>{ article.title }</title>
+</svelte:head>
+<main class="post">
+  <h1>{ article.title }</h1>
+  <div>{ article.date }</div>
+  <div>{@html article.html }</div>
+  <div>
+    {#if article.prev }
+      <a use:link href={`/blog/posts/${article.prev}`}>prev</a>
+    {/if}
+    {#if article.next }
+      <a use:link href={`/blog/posts/${article.next}`}>next</a>
+    {/if}
+  </div>
+</main>

package/example/pages/IntParam.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  let {
+    num
+  }: {
+    num: number
+  } = $props();
+</script>
+<svelte:head>
+  <title>int param</title>
+</svelte:head>
+<main class="int-param">
+  <p class="value">value: { num }</p>
+  <p class="twice">twice: { num * 2 }</p>
+</main>

package/example/pages/Message.svelte

@@ -0,0 +1,9 @@
+<script lang="ts">
+  let { message = "" }: { message: string } = $props()
+</script>
+<svelte:head>
+  <title>Message</title>
+</svelte:head>
+<main class="message">
+  {#if message}<p>{message}</p>{/if}
+</main>

package/example/pages/Params.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  let {
+    params
+  }: {
+    params: { slug: string }
+  } = $props();
+</script>
+<svelte:head>
+  <title>Slug { params.slug }</title>
+</svelte:head>
+<main class="params">
+  <p class="slug">slug: { params.slug }</p>
+</main>

package/{examples/app-svelte4/src → example/pages}/Query.svelte

@@ -1,13 +1,14 @@
 <script>
   import { link, currentURL } from "svelte-spa-history-router";
 
-  $: name = $currentURL.searchParams.get("name") ?? 'unknown';
+
+  let name = $derived(currentURL().searchParams.get("name") ?? 'unknown');
 </script>
 <svelte:head>
   <title>query</title>
 </svelte:head>
-<div class="query">
+<main class="query">
   <p>name: <span id="name">{ name }</span></p>
   <a use:link href="/query?name=foo">foo</a>
   <a use:link href="/query?name=bar">bar</a>
-</div>
+</main>

package/example/pages/Top.svelte

@@ -0,0 +1,7 @@
+<svelte:head>
+  <title>Top</title>
+</svelte:head>
+<h1>Top</h1>
+<main class="top">
+  Basic route.
+</main>

package/example/types.ts

@@ -0,0 +1,9 @@
+
+export interface Article {
+  id: string;
+  title: string;
+  date: string;
+  html: string;
+  next?: string;
+  prev?: string;
+}

package/package.json

@@ -1,28 +1,32 @@
 {
   "name": "svelte-spa-history-router",
-  "version": "2.2.0",
+  "version": "3.0.0-next.2",
   "description": "History base router for Svelte SPA",
   "type": "module",
-  "main": "src/index.js",
-  "svelte": "src/index.js",
+  "main": "src/index.ts",
+  "svelte": "src/index.ts",
   "exports": {
     ".": {
-      "svelte": "./src/index.js"
+      "svelte": "./src/index.ts"
     }
   },
-  "types": "src/index.d.ts",
   "scripts": {
-    "dev": "cd examples/app-svelte4 && npm run dev",
-    "test": "cd examples/app-svelte4 && npm run test",
-    "format": "prettier --write 'src/**/*.js'",
-    "check": "npx svelte-check"
+    "dev": "vite",
+    "test": "playwright test",
+    "check": "svelte-check --tsconfig ./tsconfig.app.json && tsc -p tsconfig.node.json"
   },
   "peerDependencies": {
-    "svelte": "*"
+    "svelte": ">5.0.0"
   },
   "devDependencies": {
-    "prettier": "3.3.3",
-    "svelte": "4.2.19"
+    "@playwright/test": "1.49.1",
+    "@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"
   },
   "author": "ykrods",
   "license": "MIT",