@nano_kit/router 1.0.0-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 - present, TrigenSoftware
+
+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,114 @@
+# @nano_kit/router
+
+[![ESM-only package][package]][package-url]
+[![NPM version][npm]][npm-url]
+[![Dependencies status][deps]][deps-url]
+[![Install size][size]][size-url]
+[![Build status][build]][build-url]
+[![Coverage status][coverage]][coverage-url]
+
+[package]: https://img.shields.io/badge/package-ESM--only-ffe536.svg
+[package-url]: https://nodejs.org/api/esm.html
+
+[npm]: https://img.shields.io/npm/v/@nano_kit/router.svg
+[npm-url]: https://npmjs.com/package/@nano_kit/router
+
+[deps]: https://img.shields.io/librariesio/release/npm/@nano_kit/router
+[deps-url]: https://libraries.io/npm/@nano_kit/router/tree
+
+[size]: https://deno.bundlejs.com/badge?q=@nano_kit/router
+[size-url]: https://bundlejs.com/?q=@nano_kit/router
+
+[build]: https://img.shields.io/github/actions/workflow/status/TrigenSoftware/nano_kit/tests.yml?branch=main
+[build-url]: https://github.com/TrigenSoftware/nano_kit/actions
+
+[coverage]: https://img.shields.io/codecov/c/github/TrigenSoftware/nano_kit.svg
+[coverage-url]: https://app.codecov.io/gh/TrigenSoftware/nano_kit
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="../../website/src/assets/ring-system_white.svg">
+  <img alt="Four-pointed ring system star logo" src="../../website/src/assets/ring-system_black.svg" width="100" height="100" align="right">
+</picture>
+
+A small and powerful router for [@nano_kit/store](../store) state manager.
+
+- **Small**. Around 2 kB (minified & brotlied). Zero dependencies except [@nano_kit/store](../store).
+- **Type-safe**. Full TypeScript support with type inference for routes and parameters.
+- **Signal-based**. Built on top of [@nano_kit/store](../store)'s reactive signals for automatic UI updates.
+- **Flexible**. Supports nested layouts, parameterized routes, optional parameters, wildcards, and query parameters.
+- **SSR-ready**. Works seamlessly with server-side rendering.
+
+## Installation
+
+```bash
+pnpm add @nano_kit/store @nano_kit/router
+# or
+npm install @nano_kit/store @nano_kit/router
+# or
+yarn add @nano_kit/store @nano_kit/router
+```
+
+## Quick Start
+
+Here is a minimal example demonstrating navigation, routing, and reactive page rendering:
+
+```js
+import { effect } from '@nano_kit/store'
+import { browserNavigation, router, page, layout, notFound } from '@nano_kit/router'
+
+/* Define your routes */
+const routes = {
+  home: '/',
+  user: '/users/:id',
+  userPosts: '/users/:id/posts',
+  admin: '/admin/*'
+}
+
+/* Setup navigation with browser history */
+const [$location, navigation] = browserNavigation(routes)
+
+/* Define page components */
+const HomePage = () => 'Welcome Home!'
+const UserPage = () => `User ID: ${$location().params.id}`
+const UserPostsPage = () => `Posts for User: ${$location().params.id}`
+const AdminLayout = ($page) => `Admin Layout: ${$page()}`
+const AdminPage = () => `Admin Page: ${$location().params.wildcard || 'dashboard'}`
+const NotFoundPage = () => 'Page Not Found'
+
+/* Create router with pages and layouts */
+const [$page] = router($location, [
+  page('home', HomePage),
+  page('user', UserPage),
+  page('posts', UserPostsPage),
+  layout(AdminLayout, [
+    page('admin', AdminPage)
+  ]),
+  notFound(NotFoundPage)
+], composeLayoutFunction)
+
+/* React to route changes (mounting $page triggers router) */
+const unsub = effect(() => {
+  const PageComponent = $page()
+
+  console.log('Current page:', PageComponent())
+  // Render PageComponent in your app
+})
+// Output: Current page: Welcome Home!
+
+/* Navigate programmatically */
+navigation.push('/users/123')
+// Output: Current page: User ID: 123
+
+navigation.push('/admin/settings/profile')
+// Output: Current page: Admin Layout: Admin Page: settings/profile
+
+navigation.back()
+// Output: Current page: User ID: 123
+
+/* Cleanup */
+unsub()
+```
+
+## Documentation
+
+For comprehensive guides, advanced patterns, and API reference, visit the [documentation website](https://nano_kit.js.org/router).

package/dist/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const PushHistoryAction = "push";
+export declare const ReplaceHistoryAction = "replace";
+export declare const PopHistoryAction = "pop";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,SAAS,CAAA;AACvC,eAAO,MAAM,oBAAoB,YAAY,CAAA;AAC7C,eAAO,MAAM,gBAAgB,QAAQ,CAAA"}

package/dist/di.d.ts

@@ -0,0 +1,45 @@
+import { type InjectionFactory, type ReadableSignal } from '@nano_kit/store';
+import type { Routes } from './types.js';
+import { type Navigation, type RouteLocationRecord } from './navigation.js';
+import { type LayoutMatchRef, type PageMatchRef, type StoresPreload } from './router.js';
+/**
+ * Create browser navigation and location injection factories.
+ * @param routes - Routes object defining path patterns.
+ * @returns Tuple of location and navigation injection factories.
+ */
+export declare function browserNavigation$<const R extends Routes = {}>(routes?: R): [
+    InjectionFactory<RouteLocationRecord<R>>,
+    InjectionFactory<Navigation>
+];
+/**
+ * Create virtual navigation and location injection factories.
+ * @param initialPath - Initial path for the virtual navigation (default: '/').
+ * @param routes - Routes object defining path patterns.
+ * @returns Tuple of location and navigation injection factories.
+ */
+export declare function virtualNavigation$<const R extends Routes = {}>(initialPath?: string, routes?: R): [
+    InjectionFactory<RouteLocationRecord<R>>,
+    InjectionFactory<Navigation>
+];
+/**
+ * Creates a current route matching page injection factory.
+ * @param Location$ - Injection factory for the route location record.
+ * @param pages - Array of page match references.
+ * @returns Tuple of page injection factory and stores preload injection factory.
+ */
+export declare function router$<R extends Routes, K extends keyof R & string, P>(Location$: InjectionFactory<RouteLocationRecord<R>>, pages: (PageMatchRef<NoInfer<K>, P> | PageMatchRef<null, P>)[]): [
+    InjectionFactory<ReadableSignal<P | null>>,
+    InjectionFactory<StoresPreload>
+];
+/**
+ * Creates a current route matching page and layout injection factory.
+ * @param Location$ - Injection factory for the route location record.
+ * @param pages - Array of page and layout match references.
+ * @param compose - Function to compose layouts with nested content.
+ * @returns Tuple of page injection factory and stores preload injection factory.
+ */
+export declare function router$<R extends Routes, K extends keyof R & string, P, N, L, C>(Location$: InjectionFactory<RouteLocationRecord<R>>, pages: (PageMatchRef<NoInfer<K>, P> | PageMatchRef<null, P> | LayoutMatchRef<NoInfer<K>, N, L>)[], compose: ($nested: ReadableSignal<N | null>, layout: L) => C): [
+    InjectionFactory<ReadableSignal<P | C | null>>,
+    InjectionFactory<StoresPreload>
+];
+//# sourceMappingURL=di.d.ts.map

package/dist/di.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"di.d.ts","sourceRoot":"","sources":["../src/di.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EAEpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EACL,KAAK,UAAU,EACf,KAAK,mBAAmB,EAGzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,aAAa,EAInB,MAAM,aAAa,CAAA;AAEpB;;;;GAIG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,EAC5D,MAAM,GAAE,CAAW,GAClB;IACD,gBAAgB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,CAAC,UAAU,CAAC;CAC7B,CASA;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,GAAG,EAAE,EAC5D,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,CAAC,GACT;IACD,gBAAgB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACxC,gBAAgB,CAAC,UAAU,CAAC;CAC7B,CASA;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,EACrE,SAAS,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EACnD,KAAK,EAAE,CACH,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC3B,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CACxB,EAAE,GACF;IACD,gBAAgB,CAAC,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAC1C,gBAAgB,CAAC,aAAa,CAAC;CAChC,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAC9E,SAAS,EAAE,gBAAgB,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EACnD,KAAK,EAAE,CACH,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAC3B,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,GACrB,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CACnC,EAAE,EACH,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,GAC3D;IACD,gBAAgB,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9C,gBAAgB,CAAC,aAAa,CAAC;CAChC,CAAA"}

package/dist/diy.d.ts

@@ -0,0 +1,51 @@
+import type { Navigation } from './navigation.js';
+/**
+ * Handle link click events to navigate using the router.
+ * @param this - Router navigation object
+ * @param event - MouseEvent from the click
+ */
+export declare function onLinkClick(this: Navigation, event: Pick<MouseEvent, 'target' | 'button' | 'defaultPrevented' | 'altKey' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'preventDefault'>): void;
+/**
+ * Effect to listen for link clicks and navigate using the router.
+ * @param navigation - Router navigation object
+ * @returns Cleanup function to remove the event listener
+ */
+export declare function listenLinks(navigation: Navigation): () => void;
+/**
+ * Reset scroll position to the top of the page.
+ */
+export declare function resetScroll(): void;
+/**
+ * Scroll to an anchor on the page.
+ * @param hash - The anchor hash (e.g., #section1)
+ * @param options - `scrollIntoView` options
+ */
+export declare function scrollToAnchor(hash: string, options?: ScrollIntoViewOptions): void;
+/**
+ * Utility class to save and restore scroll positions using session storage.
+ */
+export declare class ScrollRestorator {
+    #private;
+    /**
+     * Create a ScrollRestorator instance.
+     * @param storageKeyPrefix - Prefix for session storage keys
+     */
+    constructor(storageKeyPrefix?: string);
+    /**
+     * Save the current scroll position for the given location.
+     * @param location - The location object
+     */
+    save(location: Location): void;
+    /**
+     * Restore the scroll position for the given location.
+     * @param location - The location object
+     * @returns True if a saved position was restored, false otherwise
+     */
+    restore(location: Location): boolean;
+    /**
+     * Clear the saved scroll position for the given location.
+     * @param location - The location object
+     */
+    clear(location: Location): void;
+}
+//# sourceMappingURL=diy.d.ts.map

package/dist/diy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diy.d.ts","sourceRoot":"","sources":["../src/diy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,gBAAgB,CAAC,QAqBrI;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,UAAU,cAQjD;AAED;;GAEG;AACH,wBAAgB,WAAW,SAE1B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,QAS3E;AAED;;GAEG;AACH,qBAAa,gBAAgB;;IAG3B;;;OAGG;gBACS,gBAAgB,SAAU;IAItC;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,QAAQ;IAIvB;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,QAAQ;IAc1B;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,QAAQ;CAGzB"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './types.js';
+export * from './constants.js';
+export * from './diy.js';
+export * from './utils.js';
+export * from './navigation.js';
+export * from './searchParams.js';
+export * from './paths.js';
+export * from './router.js';
+export * from './di.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,SAAS,CAAA"}