feat: improve navigate traversing api (#37)

Author: colinlienard

.changeset/clear-sites-attend.md

@@ -0,0 +1,5 @@
+---
+'sv-router': patch
+---
+
+Improve navigate traversing api

docs/guide/common/navigation.md

@@ -80,9 +80,15 @@ navigate('/post/:slug', {
 });
 ```
 
-For browser history navigation, use:
+The `navigate` function also supports traversing through browser history, similar to the native [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API):
 
 ```ts
-navigate.back();
-navigate.forward();
+// Go back one page (equivalent to the browser's back button)
+navigate(-1);
+
+// Go forward one page (equivalent to the browser's forward button)
+navigate(1);
+
+// Go back two pages
+navigate(-2);
 ```

docs/reference/index.md

@@ -38,19 +38,16 @@ Programmatically navigate to a route.
 
 **Parameters:**
 
-- `path` - The route to navigate to
+- `path | number` - Either:
+  - A string path to navigate to, or
+  - A number representing steps to navigate in history (negative for back, positive for forward)
 - `options` - (Optional) Navigation options
   - `replace` - Replace current history entry instead of pushing
   - `search` - Query string
   - `state` - History state to save
   - `hash` - URL hash fragment
   - `params` - Parameters to substitute in the path
 
-**Methods:**
-
-- `navigate.back()` - Navigate back in history
-- `navigate.forward()` - Navigate forward in history
-
 #### `isActive(path, params?)`
 
 Checks if a given path is currently active.

src/create-router.svelte.js

@@ -57,10 +57,14 @@ export function createRouter(r) {
 }
 
 /**
- * @param {string} path
+ * @param {string | number} path
  * @param {import('./index.d.ts').NavigateOptions & { params?: Record<string, string> }} options
  */
 function navigate(path, options = {}) {
+	if (typeof path === 'number') {
+		globalThis.history.go(path);
+		return;
+	}
 	if (options.params) {
 		path = constructPath(path, options.params);
 	}
@@ -72,8 +76,6 @@ function navigate(path, options = {}) {
 	}
 	onNavigate(path, options);
 }
-navigate.back = () => globalThis.history.back();
-navigate.forward = () => globalThis.history.forward();
 
 /**
  * @param {string} [path]

src/index.d.ts

@@ -96,18 +96,15 @@ export type RouterApi<T extends Routes> = {
 	 * 	},
 	 * });
 	 * // Back and forward
-	 * navigate.back();
-	 * navigate.forward();
+	 * navigate(-1);
+	 * navigate(2);
 	 * ```
 	 *
 	 * @param route The route to navigate to.
 	 * @param options The navigation options.
 	 */
-	navigate: {
-		<U extends Path<T>>(...args: NavigateArgs<U>): void;
-		back: () => void;
-		forward: () => void;
-	};
+	navigate<U extends Path<T>>(...args: NavigateArgs<U>): void;
+
 	/**
 	 * Will return `true` if the given path is active.
 	 *
@@ -163,9 +160,10 @@ export type NavigateOptions =
 	| undefined;
 
 type NavigateArgs<T extends string> =
-	PathParams<T> extends never
-		? [T] | [T, NavigateOptions]
-		: [T, NavigateOptions & { params: PathParams<T> }];
+	| (PathParams<T> extends never
+			? [T] | [T, NavigateOptions]
+			: [T, NavigateOptions & { params: PathParams<T> }])
+	| [number];
 
 type StripNonRoutes<T extends Routes> = {
 	[K in keyof T as K extends `*${string}`