WJFE N-Savant

https://github.com/wjsoftware/wjfe-n-savant
Admin
N-Savant is a client-side router for Svelte v5 SPAs that offers unique features like simultaneous...
Tokens:16,701
Snippets:78
Trust Score:5.3
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Svelte Multi-Universe Routing Setup Example

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Demonstrates how to set up nested routers for different routing universes within a Svelte application. It shows the use of `Router` and `Route` components with `hash` and `path` props to define distinct routing contexts.

```svelte
<Router>
    <Route path="/hash-feature/*">
        <Router hash>
            <Route hash path="/">
                <RouteHashHome />
            </Route>
            <Route path="/non-hash-route">
                <NonHashContentForSomeReason />
            </Route>
        </Router>
    </Route>
</Router>
```

--------------------------------

### Install @wjfe/n-savant Package

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Installs the @wjfe/n-savant package using npm. This is the first step before using the library in your project.

```bash
npm i @wjfe/n-savant
```

--------------------------------

### TypeScript Library Initialization Examples

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Shows how to initialize the N-Savant routing library with different configurations, including standard initialization and multi-hash mode. It also demonstrates the use of the `afterAll` hook for cleanup, particularly in testing scenarios.

```typescript
// Standard init
const cleanup = init();

// Multi hash mode
const cleanup = init({ hashMode: 'multi' });

// Always cleanup
afterAll(() => {
    cleanup();
});
```

--------------------------------

### Setup Router Test Environment in TypeScript

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Provides utilities for setting up and tearing down a router test environment. It includes functions to initialize the router context and dispose of it after tests. Usage is demonstrated with `beforeEach` and `afterAll` hooks.

```typescript
// Full source in src/testing/test-utils.ts
function createRouterTestSetup(hash: Hash | undefined): {
    readonly hash: Hash | undefined;
    readonly router: RouterEngine;
    readonly context: Map<any, any>;
    init: () => void;
    dispose: () => void;
};

// Usage in tests
beforeEach(() => {
    setup.init(); // Fresh router for each test
});

afterAll(() => {
    setup.dispose(); // Clean disposal
});
```

--------------------------------

### Route Parameter Binding Test Example (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

A comprehensive example demonstrating how to test route parameter binding. It uses the getter/setter pattern with Vitest utilities to render a component, simulate navigation, and assert that route parameters are correctly captured and processed.

```typescript
test("Should bind route parameters correctly.", async () => {
    // Arrange
    const { hash, context } = setup;
    let capturedParams: any;
    const paramsSetter = vi.fn((value) => { capturedParams = value; });

    // Act
    render(TestRouteWithRouter, {
        props: {
            hash,
            routePath: "/user/:userId",
            get params() { return capturedParams; },
            set params(value) { paramsSetter(value); },
            children: createTestSnippet('<div>User {params?.userId}</div>')
        },
        context
    });

    // Navigate to matching route
    const shouldUseHash = (ru.implicitMode === 'hash') || (hash === true) || (typeof hash === 'string');
    location.url.href = shouldUseHash ? "http://example.com/#/user/42" : "http://example.com/user/42";
    await vi.waitFor(() => {});

    // Assert
    expect(paramsSetter).toHaveBeenCalled();
    expect(capturedParams).toEqual({ userId: 42 }); // Note: number due to auto-conversion
});

```

--------------------------------

### Snippet Creation Utilities (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Provides examples of how to create test snippets for component content using helper utilities. It shows both a recommended approach using `createTestSnippet` and a manual method with `createRawSnippet` for more control.

```typescript
// Using test utility (recommended)
const content = createTestSnippet("Component content text");

// Manual creation
const contentText = "Component content.";
const content = createRawSnippet(() => {
    return {
        render: () => `<div>${contentText}</div>`
    };
});

```

--------------------------------

### Svelte Route with Rest Parameter for 'Starts With' Matching

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Illustrates how to configure a Svelte route to match paths that start with a specific prefix using the `/*` rest parameter. This is an alternative to exact path matching.

```svelte
<Route key="admin" path="/admin/*">
  ...
</Route>
```

--------------------------------

### Basic Link Component Usage (Svelte)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Link/README.md

Demonstrates basic usage of the Link component for path and hash routing. These examples do not require a parent router. The `hash` prop controls whether the URL uses path-based routing or hash-based routing.

```svelte
<Link hash="false" href="/new/path">Path Routing => https://example.com/new/path</Link>

<Link hash="true" href="/new/path">Hash Routing => https://example.com/#/new/path</Link>

<Link hash="path1" href="/new/path">
  Multi Hash Routing => https://example.com/#path1=/new/path
  Will also preserve any other named paths
</Link>
```

--------------------------------

### Route Parameters in Svelte Router

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Router/README.md

Explains how to define route parameters using the `:<name>[?]` syntax. Optional parameters are indicated by a `?`. The example shows how to access these parameters within the route's snippet.

```svelte
<script lang="ts">
  import { Router, Route } from '@wjfe/n-savant';
  import UserProfile from '$lib/components/user-profile.svelte';
  import UserDetails from '$lib/components/user-details.svelte';
</script>

<Router>
  <Route path="/user/:id/:detailed?">
    {#snippet children(params)}
      <UserProfile id={params.id} />
      {#if params.detailed}
        <UserDetails id={params.id} />
      {/if}
    {/snippet}
  </Route>
</Router>
```

--------------------------------

### wjfe-n-savant Route with Rest Parameter (Catch-all)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/demo/src/lib/views/path-routing/code-samples/route-parameters.txt

Shows how to implement a catch-all route using a rest parameter. The '*' syntax captures any remaining path segments and makes them available as an array under the 'rest' key in the 'params' object. This is ideal for file explorers or handling deeply nested routes.

```html
<Route key="files" path="/files/*">
  {#snippet children(params)}
    <FileExplorer path={params.rest} />
  {/snippet}
</Route>
```

--------------------------------

### Using LinkContext for Bulk Link Configuration (Svelte)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/LinkContext/README.md

This example shows how to use the LinkContext component to apply common properties (prependBasePath, preserveQuery) to multiple Link components within its scope, contrasting it with setting each property individually. The context is inherited by all child links.

```svelte
<LinkContext prependBasePath preserveQuery>
  <Link href="...">...</Link>
  <Link href="...">...</Link>
  <Link href="...">...</Link>
</LinkContext>
```

--------------------------------

### Svelte Routes with Parameter Type Checking using 'and' Property

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Demonstrates how to enforce specific parameter types for routes in Svelte using the `and` property with a predicate function. This example ensures `userId` is a number for one route.

```svelte
<Route path="/users/:userId" and={(rp) => typeof rp.userId === 'number'}>
  {#snippet children(rp)}
    <UserDetails userId={rp.userId} />
  {/snippet}
</Route>
<Route path="/users/summary">
  <UsersSummary />
</Route>
```

--------------------------------

### wjfe-n-savant Route with Multiple Parameters

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/demo/src/lib/views/path-routing/code-samples/route-parameters.txt

Illustrates how to define a route that captures multiple distinct parameters from the URL path. Each parameter is named in the path and can be accessed individually through the 'params' object in the child component. This is common for structured content like blog posts.

```html
<Route key="post" path="/blog/:category/:slug">
  {#snippet children(params)}
    <BlogPost 
      category={params.category} 
      slug={params.slug} 
    />
  {/snippet}
</Route>
```

--------------------------------

### Flexible Route Setup with addRoutes Utility (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Illustrates various ways to use the `addRoutes` utility for configuring routes in tests. It supports simple counts of matching/non-matching routes, custom `RouteSpecs` for detailed definitions, and rest parameters for explicit route declarations with patterns, regex, and optional names. This utility enhances flexibility and type safety in route management.

```typescript
// Simple route counts
addRoutes(router, { matching: 2, nonMatching: 1 });

// RouteSpecs approach for custom route definitions
addRoutes(router, { 
    matching: { count: 2, specs: { pattern: "/custom/:id" } },
    nonMatching: { count: 1, specs: { pattern: "/other" } }
});

// Rest parameters for explicit route definitions (NEW)
addRoutes(router, 
    { matching: 1, nonMatching: 0 },
    { pattern: "/api/users/:id", name: "user-detail" },
    { regex: /^\/products\/\d+$/, name: "product" },
    { pattern: "/settings" } // Name auto-generated if not provided
);

// Combined approach
addRoutes(router,
    { matching: 2 }, // Generate 2 matching routes
    { pattern: "/custom", name: "custom-route" }, // Add specific route
    { pattern: "/another" } // Add another with auto-generated name
);
```

--------------------------------

### TypeScript: Self-Documenting Test Constants with Dictionaries

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

This example demonstrates the use of dictionary-based constants for improved test maintainability and readability. Instead of using raw boolean values, it leverages imported constants from `test-utils.js`. This approach enhances type safety, provides a single source of truth for constant values, and improves discoverability through IDE autocomplete.

```typescript
// Import self-documenting hash values
import { ALL_HASHES } from "../testing/test-utils.js";

// Usage in tests
test("Should validate hash compatibility.", () => {
    expect(() => {
        new RouterEngine({ hash: ALL_HASHES.single });
    }).not.toThrow();
});
```

--------------------------------

### Avoid Wrapper Components for Simple Binding Tests (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Demonstrates an anti-pattern where a wrapper component is unnecessarily used for simple binding tests. This approach overcomplicates the test setup and should be avoided in favor of more direct testing methods.

```typescript
// Bad - overcomplicated
const WrapperComponent = () => {
    let boundValue = $state();
    return `<Component bind:property={boundValue} />`;
};

```

--------------------------------

### Reacting to Navigation Events using Typescript

Source: https://context7.com/wjsoftware/wjfe-n-savant/llms.txt

Shows how to react to navigation events in a Typescript application using `@wjfe/n-savant` in full mode. Demonstrates how to use `beforeNavigate` to potentially cancel navigation based on certain conditions and `navigationCancelled` to handle cancelled navigations. Includes setup with `initFull` and unsubscribe functions.

```typescript
import { location, initFull } from '@wjfe/n-savant';

// Initialize in full mode to enable navigation events
initFull();

// beforeNavigate - cancellable navigation event
const unsubscribe1 = location.on('beforeNavigate', (event) => {
  console.log('Navigating to:', event.url);
  console.log('With state:', event.state);
  console.log('Method:', event.method); // 'push' or 'replace'

  // Cancel navigation conditionally
  if (!userIsAuthenticated) {
    event.cancel('User not authenticated');
  }

  // Check if already cancelled by previous handler
  if (event.wasCancelled) {
    console.log('Navigation cancelled by another handler:', event.cancelReason);
  }
});

// navigationCancelled - triggered when navigation is cancelled
const unsubscribe2 = location.on('navigationCancelled', (event) => {
  console.log('Navigation cancelled:', event.url);
  console.log('Reason:', event.cause);
  console.log('Method:', event.method);

  // Show user feedback
  alert(`Cannot navigate: ${event.cause}`);
});

// Clean up event listeners
unsubscribe1();
unsubscribe2();

```

--------------------------------

### TypeScript Effect for Reacting to Location Changes

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Provides a TypeScript example using `$effect` to reactively monitor changes in the global `location` object's properties (`url`, `state`, `hashPaths`). This allows for side effects based on navigation events.

```typescript
import { location } from "@wjfe/n-savant";

// Or $derived, whichever you need.
$effect(() => {
  // Read location.url to re-run on URL changes (navigation).
  location.url;
  // Read location.state to re-run on state changes.
  location.state;
  // Read location.hashPaths to re-run on hash changes (hash navigation).
  // The route named "single" is the one you want if doing hash routing.
  location.hashPaths.single;
});
```

--------------------------------

### wjfe-n-savant Route with Single Parameter

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/demo/src/lib/views/path-routing/code-samples/route-parameters.txt

Defines a route that captures a single parameter from the URL, typically an ID. The captured parameter is accessible within the route's children component via the 'params' object. This is useful for fetching specific resources like user profiles.

```html
<Route key="user" path="/user/:id">
  {#snippet children(params)}
    <h1>User ID: {params.id}</h1>
  {/snippet}
</Route>
```

--------------------------------

### Svelte Route with Parameter Type Checking using Regular Expression

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Shows an alternative method for parameter type checking in Svelte routes by using a regular expression directly in the `path` property. This example uses `\d+` to match numeric user IDs.

```svelte
<Route path={/\/users\/(?<userId>\d+)/i}>
  {#snippet children(rp)}
    <UserDetails userId={rp.userId} />
  {/snippet}
</Route>
<Route path="/users/summary">
  <UsersSummary />
</Route>
```

--------------------------------

### Testing Observable Behavior vs. Implementation in TypeScript

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Demonstrates the principle of testing observable behavior rather than internal implementation details. The example shows a 'good' test that asserts the user-visible outcome (hidden content) and a 'bad' test that spies on an internal method call, highlighting the importance of testing the 'what' not the 'how'.

```typescript
// ✅ Good - Test what the user sees
test("Should hide content when routes match.", () => {
    addMatchingRoute(router);
    const { queryByText } = render(Component, { props, context });
    expect(queryByText("content")).toBeNull();
});

// ❌ Bad - Test internal implementation
test("Should call router.noMatches.", () => {
    const spy = vi.spyOn(router, 'noMatches');
    render(Component, { props, context });
    expect(spy).toHaveBeenCalled(); // Testing implementation detail
});
```

--------------------------------

### TypeScript: Universe-Based Testing Pattern for Full Routing Coverage

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

This pattern ensures complete test coverage across all 5 routing universes by iterating through predefined universe configurations. It utilizes `beforeAll`, `afterAll`, `beforeEach`, and `afterEach` hooks for setup and teardown, ensuring a consistent test environment for each universe. Test logic within the `test` block is designed to work across all universes, with specific assertions verifying expected behavior.

```typescript
import { ROUTING_UNIVERSES } from "../testing/test-utils.js";

// ✅ Recommended: Test ALL universes with single loop
ROUTING_UNIVERSES.forEach((universe) => {
    describe(`Component (${universe.text})`, () => {
        let cleanup: () => void;
        let setup: ReturnType<typeof createRouterTestSetup>;
        
        beforeAll(() => {
            cleanup = init({
                implicitMode: universe.implicitMode,
                hashMode: universe.hashMode
            });
            setup = createRouterTestSetup(universe.hash);
        });
        
        afterAll(() => {
            cleanup();
            setup.dispose();
        });
        
        beforeEach(() => {
            setup.init(); // Fresh router per test
            setupBrowserMocks("/"); // Fresh browser state
        });
        
        test(`Should behave correctly in ${universe.text}`, () => {
            // Test logic that works across all universes
            const { hash, context, router } = setup;
            
            // Use universe.text for concise test descriptions
            expect(universe.text).toMatch(/^(IMP|IMH|PR|HR|MHR)$/);
        });
    });
});
```

--------------------------------

### Default Props Tests in TypeScript

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Tests component behavior with minimal or default property values. It initializes a test setup, renders the component with default props, and asserts its behavior. This pattern is useful for ensuring basic functionality works as expected.

```typescript
function defaultPropsTests(setup: ReturnType<typeof createRouterTestSetup>) {
    beforeEach(() => setup.init());
    afterAll(() => setup.dispose());
    
    test("Should behave correctly with default props.", () => {
        // Test with hash: undefined and minimal props
        const { hash, context } = setup;
        render(Component, { props: { hash, children: content }, context });
        // Assert default behavior
    });
}
```

--------------------------------

### Test Isolation with beforeEach in TypeScript

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Ensures test isolation by setting up a fresh instance for each test using `beforeEach`. This guarantees that tests do not interfere with each other by sharing state. The example contrasts this with a 'bad' practice of reusing router instances across tests using `beforeAll`.

```typescript
// ✅ Fresh instance for each test
beforeEach(() => {
    setup.init(); // Creates new router
});

// ❌ Reusing router instances
beforeAll(() => {
    setup.init(); // Same router for all tests - bad!
});
```

--------------------------------

### Implement Nested Routers with Base Paths

Source: https://context7.com/wjsoftware/wjfe-n-savant/llms.txt

This Svelte example demonstrates creating nested routers using '@wjfe/n-savant'. It shows how a parent router can define a `basePath` (e.g., '/admin') which is inherited by its child routers, allowing for hierarchical routing structures. Routes within nested routers are matched relative to their parent's base path.

```svelte
<script lang="ts">
  import { Router, Route } from '@wjfe/n-savant';
</script>

<!-- Parent router with base path -->
<Router hash={false} basePath="/admin" id="admin-router">
  <Route key="admin-home" path="/">
    <h1>Admin Home</h1>
  </Route>

  <Route key="users-section" path="/users/*">
    {#snippet children(params)}
      <!-- Nested router inherits /admin/users as base -->
      <Router id="users-router">
        <!-- Matches /admin/users/list -->
        <Route key="user-list" path="/list">
          <p>User List</p>
        </Route>

        <!-- Matches /admin/users/create -->
        <Route key="user-create" path="/create">
          <p>Create User</p>
        </Route>

        <!-- Matches /admin/users/123/edit -->
        <Route key="user-edit" path="/:id/edit">
          {#snippet children(params)}
            <p>Edit User {params.id}</p>
          {/snippet}
        </Route>
      </Router>
    {/snippet}
  </Route>
</Router>
```

--------------------------------

### Initialize @wjfe/n-savant Library

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Initializes the @wjfe/n-savant routing library. Demonstrates default initialization and configuration for hash-based routing.

```typescript
// In your main.ts, or somewhere BEFORE any routers are created:
import { init } from "@wjfe/n-savant";

// Default:  Lite mode, implicit path routing, no router hierarchy tracing, single hash mode. 
init();

// If all you care about is (traditional) hash routing, the recommendation is to change the implicit mode:
init({ implicitMode: 'hash' });
```

--------------------------------

### goTo() - Direct URL Navigation

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

The goTo() method provides direct URL navigation without routing universe awareness. Use this for external navigation or when direct URL control is needed.

```APIDOC
## goTo(url, options)

### Description
Provides direct URL navigation without routing universe awareness. Requires a complete `State` object if provided.

### Method
`location.goTo`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL to navigate to.
- **options** (object) - Optional - Navigation options.
  - **replace** (boolean) - Optional - Replace the current URL entry in history (defaults to `false`).
  - **state** (object) - Required if navigating to a new URL - Complete state object conforming to library expectations (e.g., `{ path: undefined, hash: {} }`).
  - **preserveQuery** (string | string[]) - Optional - Preserve specific query parameters by name or an array of names.

### Request Example
```json
// Direct URL navigation
location.goTo('https://example.com/new/path', {
  replace: true,
  state: { path: undefined, hash: {} } // Must provide complete State object
});

// Shallow routing (navigate to current URL)
location.goTo('', {
  replace: true
});

// Preserve query parameters
location.goTo('/new/path', {
  preserveQuery: ['param1', 'param2']
});
```

### Response
#### Success Response (200)
This method does not return a response body, but initiates navigation.

#### Response Example
N/A
```

--------------------------------

### Options Reference

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Details on the common and specific options available for navigation methods.

```APIDOC
## Navigation Options Reference

### Common Options (for `navigate()` and `goTo()`)
- **`replace?: boolean`**: Replace the current URL in the history stack instead of pushing a new entry. Defaults to `false`.
- **`preserveQuery?: PreserveQuery`**: Controls the preservation of current query parameters.
  - `true`: Preserves all query parameters.
  - `string`: Preserves a specific query parameter by its name.
  - `string[]`: Preserves multiple specific query parameters by their names.

### `navigate()` Specific Options
- **`hash?: Hash`**: Specifies the routing universe to associate with the navigation. Accepted values are:
  - `false`: Path routing.
  - `true`: Default hash routing.
  - `string`: A named hash (e.g., 'path1') for multi-hash routing.
- **`state?: any`**: Arbitrary state data to associate with the navigation. This data will be available during the lifecycle of the navigated route.

### `goTo()` Specific Options
- **`state?: State`**: A complete state object that must conform to the library's expected structure for direct URL navigation. Example: `{ path: undefined, hash: {} }`.
```

--------------------------------

### Electron Initialization and Navigation

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Initializes the @wjfe/n-savant library and navigates to the homepage, specifically for Electron applications using path routing. Hash routing does not require this extra step.

```typescript
import { init, location } from "@wjfe/n-savant";

init();
location.goTo('/');
```

--------------------------------

### Mock Browser APIs for RouterEngine Testing (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Demonstrates how to mock browser APIs like `window.location` and `window.history` using `setupBrowserMocks` for testing components such as `RouterEngine`. This utility automatically handles mocking, state synchronization, and cleanup, ensuring reliable testing of routing behavior.

```typescript
import { setupBrowserMocks } from "../testing/test-utils.js";

describe("Component requiring browser APIs", () => {
    beforeEach(() => {
        // Automatically mocks window.location, window.history, and integrates with library Location
        setupBrowserMocks("/initial/path");
    });
    
    test("Should respond to location changes.", () => {
        // Browser APIs are now mocked and integrated with library
        window.history.pushState({}, "", "/new/path");
        // Test component behavior
    });
});
```

--------------------------------

### Basic Router Usage in Svelte

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Router/README.md

Demonstrates the simplest way to set up the Router and Route components for basic navigation. It defines three routes: /home, /about, and /contact.

```svelte
<script lang="ts">
  import { Router, Route } from '@wjfe/n-savant';
</script>

<Router>
  <Route path="/home">
    <h1>Welcome to the home page!</h1>
  </Route>
  <Route path="/about">
    <h1>About Us</h1>
  </Route>
  <Route path="/contact">
    <h1>Contact Us</h1>
  </Route>
</Router>
```

--------------------------------

### navigate() - Routing Universe Aware Navigation

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

The navigate() method is the recommended way to programmatically navigate within your application as it understands routing universes and manages state effectively.

```APIDOC
## navigate(url, options)

### Description
Navigates programmatically while being aware of routing universes and managing state.

### Method
`location.navigate`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - Required - The URL path to navigate to.
- **options** (object) - Optional - Navigation options.
  - **replace** (boolean) - Optional - Replace the current URL entry in history (defaults to `false`).
  - **state** (any) - Optional - State data to associate with the navigation.
  - **hash** (boolean | string) - Optional - Specifies the routing universe to associate with the navigation. Can be `false`, `true`, or a named hash (e.g., 'path1').
  - **preserveQuery** (boolean | string | string[]) - Optional - Preserve current query parameters. `true` preserves all, a string preserves a specific parameter by name, or an array of strings preserves multiple specific parameters.

### Request Example
```json
// Path routing navigation
location.navigate('/new/path', {
  replace: true,
  state: { custom: 'Hi' },
  hash: false
});

// Hash routing navigation
location.navigate('/new/path', {
  replace: true,
  state: { custom: 'Hi' },
  hash: true
});

// Multi-hash routing navigation
location.navigate('/new/path', {
  replace: true,
  state: { custom: 'Hi' },
  hash: 'path1'
});

// Preserve existing query parameters
location.navigate('/new/path', {
  preserveQuery: true,
  hash: false
});
```

### Response
#### Success Response (200)
This method does not return a response body, but initiates navigation.

#### Response Example
N/A
```

--------------------------------

### Direct URL Navigation with goTo()

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Illustrates using the goTo() function for direct URL navigation, bypassing routing universe awareness. This method requires a complete state object and is useful for external links or when precise URL control is needed. It can also preserve specific query parameters.

```typescript
import { location } from "@wjfe/n-savant";

// Direct URL navigation:
location.goTo('https://example.com/new/path', { 
  replace: true,
  state: { path: undefined, hash: {} }  // Must provide complete State object
});

// Shallow routing (navigate to current URL):
location.goTo('', { replace: true });

// Preserve query parameters:
location.goTo('/new/path', { 
  preserveQuery: ['param1', 'param2'] 
});
```

--------------------------------

### Individual Link Configuration (Svelte - Before LinkContext)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/LinkContext/README.md

This snippet illustrates the verbose way of configuring multiple Link components by setting properties like 'prependBasePath' and 'preserveQuery' on each individual Link component, before the introduction of the LinkContext.

```svelte
<Link prependBasePath preserveQuery href="...">...</Link>
<Link prependBasePath preserveQuery href="...">...</Link>
<Link prependBasePath preserveQuery href="...">...</Link>
<Link prependBasePath preserveQuery href="...">...</Link>
```

--------------------------------

### TypeScript: Browser Mock State Synchronization for Performance

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

This snippet highlights performance optimizations in testing by comparing automatic browser mock state synchronization with manual synchronization. The recommended approach uses `setupBrowserMocks` with the library's location object for seamless integration, automatically handling state updates. The older, less efficient method requires manual updates to `mockLocation` and explicit dispatching of `PopStateEvent`.

```typescript
// ✅ Automatic state sync - setupBrowserMocks handles this
// Best practice: pass the library's location object for full integration
setupBrowserMocks("/initial", libraryLocationObject);
window.history.pushState({}, "", "/new"); // Automatically triggers popstate

// ❌ Manual sync required (old approach)
mockLocation.pathname = "/new";
window.dispatchEvent(new PopStateEvent('popstate')); // Manual event trigger
```

--------------------------------

### Test Description Conventions (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Details the guidelines for writing clear and consistent test descriptions. Emphasizes using full sentences, proper capitalization and punctuation, and incorporating test data for data-driven tests to create unique descriptions.

```typescript
// Doesn't work:  The ending period cannot "touch" the placeholder identifier or vitest will be confused.
test.each([...])("Should ... $text.", ...);
// Workaround:  Add a space before the sentence's ending period.
test.each([...])("Should ... $text .", ...);

```

--------------------------------

### Programmatic Navigation using Typescript

Source: https://context7.com/wjsoftware/wjfe-n-savant/llms.txt

Illustrates programmatic navigation within a Typescript application using the `location` object from `@wjfe/n-savant`. It covers various navigation methods like `navigate` and `goTo`, including path and hash routing, state management, query parameter preservation, shallow routing, and history manipulation. It also shows how to access reactive routing state.

```typescript
import { location } from '@wjfe/n-savant';

// navigate() - routing universe aware (recommended for most use cases)
location.navigate('/users/456', {
  hash: false,           // Path routing universe
  replace: false,        // Push new history entry
  state: { from: 'app' },
  preserveQuery: true    // Keep existing query params
});

// Hash routing navigation
location.navigate('/dashboard', {
  hash: true,            // Single hash routing
  state: { view: 'grid' }
});

// Multi-hash routing navigation
location.navigate('/panel', {
  hash: 'sidebar',       // Named hash path
  replace: true,
  state: { collapsed: false }
});

// Path routing with hash preservation
location.navigate('/new-page', {
  hash: false,
  preserveHash: true,    // Keeps existing hash fragment
  preserveQuery: ['tab']
});

// goTo() - direct URL navigation (use sparingly)
location.goTo('https://example.com/path?query=value#hash', {
  replace: true,
  state: { path: undefined, hash: {} }, // Must provide complete State object
  preserveQuery: ['filter']
});

// Shallow routing - update state without changing URL
location.goTo('', {
  replace: true,
  state: { path: { modal: 'open' }, hash: {} }
});

// History navigation methods
location.back();           // Navigate back one entry
location.forward();        // Navigate forward one entry
location.go(-2);           // Navigate back 2 entries
location.go(1);            // Navigate forward 1 entry

// Access reactive routing state
console.log(location.url);                    // Reactive URL object
console.log(location.hashPaths.single);       // Single hash routing path
console.log(location.hashPaths.sidebar);      // Multi-hash routing path 'sidebar'
console.log(location.getState(false));        // Get path routing state
console.log(location.getState(true));         // Get hash routing state
console.log(location.getState('sidebar'));    // Get multi-hash routing state

```

--------------------------------

### Required Imports for Testing (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Lists essential imports for setting up tests using Vitest and Svelte's testing utilities. This includes core testing functions, router-specific utilities, and Svelte's rendering and reactivity helpers.

```typescript
import { init, type Hash } from "$lib/index.js";
import { describe, test, expect, beforeAll, afterAll, beforeEach } from "vitest";
import { render } from "@testing-library/svelte";
import { RouterEngine } from "$lib/core/RouterEngine.svelte.js";
import { getRouterContextKey } from "../Router/Router.svelte";
import { createRawSnippet } from "svelte";
import { flushSync } from "svelte"; // For Svelte 5 reactivity testing
import { 
    addMatchingRoute, 
    addRoutes, 
    createRouterTestSetup, 
    createTestSnippet, 
    ROUTING_UNIVERSES 
} from "../testing/test-utils.js"; // Note: moved outside $lib

```

--------------------------------

### Link Component Within Parent Router (Svelte)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Link/README.md

Illustrates using the Link component within a parent Router. This enables features like prepending the base path and automatic active state styling based on the route key. The `prependBasePath`, `activeFor`, and `activeState` props are key here.

```svelte
<Router basePath="/some/base">
  <Link
    hash="path1"
    href="/admin/users"
    prependBasePath
    activeFor="adminUsers"
    activeState={{ class: 'active', aria: { 'aria-current': 'page' } }}
  >
    Click Me!
  </Link>
  <Route key="adminUsers" path="/admin/users">
    ...
  </Route>
</Router>
```

--------------------------------

### Initialize N-Savant Router (TypeScript)

Source: https://context7.com/wjsoftware/wjfe-n-savant/llms.txt

Initializes the N-Savant router in either basic (lite) mode or full mode with History API interception. Basic initialization is suitable for most applications, while full mode enables additional events and API interception. Electron-specific initialization requires an immediate navigation call.

```typescript
import { init, initFull } from '@wjfe/n-savant';

// Basic initialization (lite mode) - suitable for most applications
init({
  implicitMode: 'path',    // 'path' or 'hash' - default routing mode when hash prop not specified
  hashMode: 'single',      // 'single' or 'multi' - enables multi-hash routing
  trace: {
    routerHierarchy: false // Enable for debugging router hierarchy (development only)
  },
  logger: true             // true, false, or custom ILogger implementation
});

// Full mode initialization - adds beforeNavigate/navigationCancelled events and History API interception
initFull({
  implicitMode: 'hash',
  logger: {
    debug: (...args) => console.debug('[Router]', ...args),
    log: (...args) => console.log('[Router]', ...args),
    warn: (...args) => console.warn('[Router]', ...args),
    error: (...args) => console.error('[Router]', ...args)
  }
});

// Electron-specific initialization - requires immediate navigation for path routing
import { location } from '@wjfe/n-savant';
init();
location.goTo('/'); // Navigate to initial route immediately
```

--------------------------------

### Svelte Lazy-Loading Component with Await Block

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Shows how to implement lazy-loading for a Svelte component using `import()` and an `await` block. This improves initial load performance by only loading components when they are needed.

```svelte
<script lang="ts">
  function loadUsersComponent() {
    return import('./lib/Users.svelte').then(m => m.default);
  }
</script>

<Route key="users" path="/users">
  {#await loadUsersComponent()}
    <span>Loading...</span>
  {:then Users}
    <Users />
  {:catch}
    <p>Oops!</p>
  {/await}
</Route>
```

--------------------------------

### Create Navigation Links using Svelte

Source: https://context7.com/wjsoftware/wjfe-n-savant/llms.txt

Demonstrates creating various types of navigation links in a Svelte application using the `Link` component from `@wjfe/n-savant`. It showcases basic links, active state styling, replace behavior, query parameter preservation, base path prepending, shallow routing, hash routing, and centralized configuration using `LinkContext`.

```svelte
<script lang="ts">
  import { Link, LinkContext } from '@wjfe/n-savant';
</script>

<!-- Basic navigation link -->
<Link href="/users/123">View User</Link>

<!-- Link with active state styling -->
<Link
  href="/users"
  activeFor="user-list"
  activeState={{
    class: 'active nav-active',
    style: { fontWeight: 'bold', color: '#007bff' },
    aria: { 'aria-current': 'page' }
  }}
>
  Users
</Link>

<!-- Replace instead of push, with custom state -->
<Link
  href="/profile"
  replace={true}
  state={{ from: 'navigation', timestamp: Date.now() }}
>
  Profile
</Link>

<!-- Preserve query parameters during navigation -->
<Link href="/search" preserveQuery={true}>
  Search (keeps all params)
</Link>

<Link href="/search" preserveQuery={['q', 'filter']}>
  Search (keeps specific params)
</Link>

<!-- Prepend router's base path to href -->
<Link href="/settings" prependBasePath={true}>
  Settings
</Link>

<!-- Shallow routing - navigate to current URL to update state only -->
<Link href="" replace={true} state={{ modal: 'open' }}>
  Open Modal
</Link>

<!-- Hash routing link -->
<Link hash={true} href="/dashboard">
  Dashboard (hash mode)
</Link>

<!-- Multi-hash routing link -->
<Link hash="sidebar" href="/menu">
  Sidebar Menu
</Link>

<!-- Centralize Link configuration with context -->
<LinkContext
  replace={false}
  prependBasePath={true}
  preserveQuery={true}
  activeState={{ class: 'is-active' }}
>
  <!-- All child Links inherit these settings -->
  <Link href="/home">Home</Link>
  <Link href="/about">About</Link>

  <!-- Override specific settings -->
  <Link href="/contact" replace={true}>Contact</Link>
</LinkContext>

```

--------------------------------

### Programmatic Path Routing Navigation with navigate()

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Demonstrates using the navigate() function for path-based routing. Supports options like replacing the history entry, adding custom state, and controlling hash usage. This method is aware of routing universes and manages state accordingly.

```typescript
import { location } from "@wjfe/n-savant";

// Path routing navigation:
location.navigate('/new/path', { 
  replace: true, 
  state: { custom: 'Hi' },
  hash: false 
});

// Hash routing navigation:
location.navigate('/new/path', { 
  replace: true, 
  state: { custom: 'Hi' },
  hash: true 
});

// Multi-hash routing navigation:
location.navigate('/new/path', { 
  replace: true, 
  state: { custom: 'Hi' },
  hash: 'path1' 
});

// Preserve existing query parameters:
location.navigate('/new/path', { 
  preserveQuery: true,
  hash: false
});
```

--------------------------------

### Use Getter/Setter for Clean, Direct Testing (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Presents a recommended pattern for testing component bindings using getter and setter functions. This approach allows for clean, direct interaction with component properties, capturing values and invoking setters for straightforward verification.

```typescript
// Good - direct, simple, effective
render(Component, {
    props: {
        get boundProperty() { return capturedValue; },
        set boundProperty(value) { propertySetter(value); }
    }
});

```

--------------------------------

### Optimize Testing Library Assertions in TypeScript

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Highlights performance tips for using testing library assertions, specifically recommending `queryByText` for negative assertions and `findByText` for positive assertions. It advises against using `expect().rejects` with `findByText` due to its inherent timeout.

```typescript
// ❌ Slow - waits 1000ms timeout
await expect(findByText(content)).rejects.toThrow();

// ✅ Fast - immediate result
expect(queryByText(content)).toBeNull();
```

--------------------------------

### Create Navigation Links (Svelte)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/README.md

Creates navigation links using the Link component from @wjfe/n-savant within a Svelte component. Supports active state styling and defines navigation targets.

```svelte
<!-- NavBar.svelte -->
<script lang="ts">
  import { Link } from "@wjfe/n-savant";
</script>

<nav>
  <div class="nav-links">
    <ul>
      <li class="nav-link">
        <Link href="/users" activeFor="users" activeState={{ class: 'active' }}>
          All Users
        </Link>
      </li>
      ...
    </ul>
  </div>
</nav>
```

--------------------------------

### Test Bindable Properties Across Routing Modes (TypeScript)

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

Tests how bindable properties behave across different routing universes (e.g., hash vs. path mode). It renders a component, sets up mock property setters, and triggers navigation to verify if the property is bound and updated correctly based on routing conditions. Assumes a testing utility `createRouterTestSetup` and `ROUTING_UNIVERSES` are defined.

```typescript
function bindablePropertyTests(setup: ReturnType<typeof createRouterTestSetup>, ru: RoutingUniverse) {
    test("Should bind property when condition is met.", async () => {
        const { hash, context } = setup;
        let capturedValue: any;
        const propertySetter = vi.fn((value) => { capturedValue = value; });

        render(Component, {
            props: {
                hash,
                get boundProperty() { return capturedValue; },
                set boundProperty(value) { propertySetter(value); },
                // Other component-specific props
            },
            context
        });

        // Trigger binding based on routing mode
        const shouldUseHash = (ru.implicitMode === 'hash') || (hash === true) || (typeof hash === 'string');
        const url = shouldUseHash ? "http://example.com/#/test" : "http://example.com/test";
        location.url.href = url;
        await vi.waitFor(() => {});

        expect(propertySetter).toHaveBeenCalled();
        expect(capturedValue).toEqual(expectedValue);
    });

    test("Should update binding when conditions change.", async () => {
        // Test binding updates during navigation or state changes
        let capturedValue: any;
        const propertySetter = vi.fn((value) => { capturedValue = value; });

        render(Component, {
            props: {
                hash,
                get boundProperty() { return capturedValue; },
                set boundProperty(value) { propertySetter(value); }
            },
            context
        });

        // First state
        await triggerFirstState();
        expect(capturedValue).toEqual(firstExpectedValue);

        // Second state
        await triggerSecondState();
        expect(capturedValue).toEqual(secondExpectedValue);
    });
}

// Apply to all routing universes
ROUTING_UNIVERSES.forEach((ru) => {
    describe(`Component - ${ru.text}`, () => {
        const setup = createRouterTestSetup(ru.hash);
        // ... setup code ...

        describe("Bindable Properties", () => {
            bindablePropertyTests(setup, ru);
        });
    });
});
```

--------------------------------

### Router with Base Path Configuration in Svelte

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Router/README.md

Illustrates how to configure a base path for the Router, useful for micro-frontend architectures or applications not served from the root directory. All routes will be prefixed with '/subpath'.

```svelte
<script lang="ts">
  import { Router, Route } from '@wjfe/n-savant';
</script>

<Router basePath="/subpath">
  ...
</Router>
```

--------------------------------

### TypeScript: Constructor Validation Testing for RouterEngine

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/AGENTS.md

This snippet shows how to systematically test constructor validation scenarios for the `RouterEngine` component, specifically focusing on hash mode compatibility between parent and child routers. It uses `test.each` to iterate over various combinations of parent and child hash modes, asserting that the correct error messages are thrown when modes are incompatible, and that no error is thrown when child routers inherit the parent's hash mode implicitly.

```typescript
describe("Constructor hash validation", () => {
    test.each([
        { parent: ALL_HASHES.path, child: ALL_HASHES.single, desc: 'path parent vs hash child' },
        { parent: ALL_HASHES.single, child: ALL_HASHES.path, desc: 'hash parent vs path child' },
        { parent: ALL_HASHES.multi, child: ALL_HASHES.path, desc: 'multi-hash parent vs path child' },
        { parent: ALL_HASHES.path, child: ALL_HASHES.multi, desc: 'path parent vs multi-hash child' }
    ])("Should throw error when parent and child have different hash modes: $desc .", ({ parent, child }) => {
        expect(() => {
            const parentRouter = new RouterEngine({ hash: parent });
            new RouterEngine(parentRouter, { hash: child });
        }).toThrow("Parent and child routers must use the same hash mode");
    });
    
    test.each([
        { parent: ALL_HASHES.path, desc: 'path parent' },
        { parent: ALL_HASHES.single, desc: 'hash parent' },
        { parent: ALL_HASHES.multi, desc: 'multi-hash parent' }
    ])("Should allow child router without explicit hash to inherit parent's hash: $desc .", ({ parent }) => {
        expect(() => {
            const parentRouter = new RouterEngine({ hash: parent });
            new RouterEngine(parentRouter);
        }).not.toThrow();
    });
});
```

--------------------------------

### Fallback Content for Unmatched Routes in Svelte

Source: https://github.com/wjsoftware/wjfe-n-savant/blob/main/src/lib/Router/README.md

Demonstrates how to provide fallback content when no defined routes match the current URL. This is achieved using the `fallback()` snippet within the Router component, typically for displaying a 404 page.

```svelte
<script lang="ts">
  import { Router, Route } from '@wjfe/n-savant';
</script>

<Router>
  <Route path="/home">
    <h1>Welcome to the home page!</h1>
  </Route>
  <Route path="/about">
    <h1>About Us</h1>
  </Route>
  <Route path="/contact">
    <h1>Contact Us</h1>
  </Route>
  {#snippet fallback()}
    <h1>404 Not Found</h1>
  {/snippet}
</Router>
```
Tokens:
Raw