feat: Add "when" property to Fallback component

Fixes #44.

Author: webJose

docs/testing-guide.md

@@ -16,7 +16,8 @@
 	"files": [
 		"dist",
 		"!dist/**/*.test.*",
-		"!dist/**/*.spec.*"
+		"!dist/**/*.spec.*",
+		"!dist/testing"
 	],
 	"sideEffects": [
 		"**/*.css"

package.json

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import { resolveHashValue } from '$lib/core/resolveHashValue.js';
 	import { getRouterContext } from '$lib/Router/Router.svelte';
-	import type { RouteStatus } from '$lib/types.js';
+	import type { RouteStatus, WhenPredicate } from '$lib/types.js';
 	import type { Snippet } from 'svelte';
 
 	type Props = {
@@ -29,6 +29,26 @@
 		 * ```
 		 */
 		hash?: boolean | string;
+		/**
+		 * Overrides the default activation conditions for the fallback content inside the component.
+		 * 
+		 * This is useful in complex routing scenarios, where fallback content is being prevented from showing due to 
+		 * certain route or routes matching at certain points, leaving no opportunity for the router to be "out of 
+		 * matching routes".
+		 * 
+		 * **This completely disconnects the `Fallback` component from the router's matching logic.**
+		 * 
+		 * @example
+		 * ```svelte
+		 * <!--
+		 * Here, onlyLayoutRoutesRemain is a function that checks if layout routes are the only ones currently matching.
+		 * -->
+		 * <Fallback when={(rs) => onlyLayoutRoutesRemain(rs)}>
+		 *     ...
+		 * </Fallback>
+		 * ```
+		 */
+		when?: WhenPredicate;
 		/**
 		 * Renders the children of the component.
 		 *
@@ -41,11 +61,11 @@
 		children?: Snippet<[any, Record<string, RouteStatus>]>;
 	};
 
-	let { hash, children }: Props = $props();
+	let { hash, when, children }: Props = $props();
 
 	const router = getRouterContext(resolveHashValue(hash));
 </script>
 
-{#if router?.noMatches}
+{#if (router && when?.(router.routeStatus, router.noMatches)) || (!when && router?.noMatches)}
 	{@render children?.(router.state, router.routeStatus)}
 {/if}

src/lib/Fallback/Fallback.svelte

@@ -0,0 +1,187 @@
+import { init } from "$lib/index.js";
+import { describe, test, expect, beforeAll, afterAll, beforeEach } from "vitest";
+import { render } from "@testing-library/svelte";
+import Fallback from "./Fallback.svelte";
+import { addMatchingRoute, addRoutes, createRouterTestSetup, createTestSnippet, ROUTING_UNIVERSES } from "$lib/testing/test-utils.js";
+import { flushSync } from "svelte";
+
+function defaultPropsTests(setup: ReturnType<typeof createRouterTestSetup>) {
+    const contentText = "Fallback content.";
+    const content = createTestSnippet(contentText);
+    
+    beforeEach(() => {
+        // Fresh router instance for each test
+        setup.init();
+    });
+    
+    afterAll(() => {
+        // Clean disposal after all tests
+        setup.dispose();
+    });
+    
+    test("Should render whenever the parent router matches no routes.", async () => {
+        // Arrange.
+        const { hash, router, context } = setup;
+
+        // Act.
+        const { findByText } = render(Fallback, { props: { hash, children: content }, context });
+
+        // Assert.
+        await expect(findByText(contentText)).resolves.toBeDefined();
+    });
+    
+    test("Should not render whenever the parent router matches at least one route.", async () => {
+        // Arrange.
+        const { hash, router, context } = setup;
+        addMatchingRoute(router);
+
+        // Act.
+        const { queryByText } = render(Fallback, { props: { hash, children: content }, context });
+
+        // Assert.
+        expect(queryByText(contentText)).toBeNull();
+    });
+}
+
+function explicitPropsTests(setup: ReturnType<typeof createRouterTestSetup>) {
+    const contentText = "Fallback content.";
+    const content = createTestSnippet(contentText);
+
+    beforeEach(() => {
+        // Fresh router instance for each test
+        setup.init();
+    });
+
+    afterAll(() => {
+        // Clean disposal after all tests
+        setup.dispose();
+    });
+
+    test.each([
+        {
+            routes: {
+                matching: 1
+            },
+            text: "matching routes"
+        },
+        {
+            routes: {
+                nonMatching: 1
+            },
+            text: "no matching routes"
+        }
+    ])("Should render when the 'when' predicate returns true when there are $text .", async ({ routes }) => {
+        // Arrange.
+        const { hash, router, context } = setup;
+        addRoutes(router, routes);
+
+        // Act.
+        const { findByText } = render(Fallback, {
+            props: { hash, when: () => true, children: content },
+            context
+        });
+
+        // Assert.
+        await expect(findByText(contentText)).resolves.toBeDefined();
+    });
+    test.each([
+        {
+            routes: {
+                matching: 1
+            },
+            text: "matching routes"
+        },
+        {
+            routes: {
+                nonMatching: 1
+            },
+            text: "no matching routes"
+        }
+    ])("Should not render when the 'when' predicate returns false when there are $text .", async ({ routes }) => {
+        // Arrange.
+        const { hash, router, context } = setup;
+        addRoutes(router, routes);
+
+        // Act.
+        const { queryByText } = render(Fallback, {
+            props: { hash, when: () => false, children: content },
+            context
+        });
+
+        // Assert.
+        expect(queryByText(contentText)).toBeNull();
+    });
+}
+
+function reactivityTests(setup: ReturnType<typeof createRouterTestSetup>) {
+    const contentText = "Fallback content.";
+    const content = createTestSnippet(contentText);
+
+    beforeEach(() => {
+        // Fresh router instance for each test
+        setup.init();
+    });
+
+    afterAll(() => {
+        // Clean disposal after all tests
+        setup.dispose();
+    });
+
+    test("Should re-render when the 'when' predicate function is exchanged.", async () => {
+        // Arrange.
+        const { hash, router, context } = setup;
+        const { findByText, queryByText, rerender } = render(Fallback, {
+            props: { hash, when: () => false, children: content },
+            context
+        });
+        expect(queryByText(contentText)).toBeNull();
+
+        // Act.
+        await rerender({ hash, when: () => true, children: content });
+
+        // Assert.
+        await expect(findByText(contentText)).resolves.toBeDefined();
+    });
+    test("Should re-render when the 'when' predicate function reactively changes its return value.", async () => {
+        // Arrange.
+        const { hash, router, context } = setup;
+        let rv = $state(false);
+        const { findByText, queryByText, rerender } = render(Fallback, {
+            props: { hash, when: () => rv, children: content },
+            context
+        });
+        expect(queryByText(contentText)).toBeNull();
+
+        // Act.
+        rv = true;
+        flushSync();
+
+        // Assert.
+        await expect(findByText(contentText)).resolves.toBeDefined();
+    });
+}
+
+ROUTING_UNIVERSES.forEach(ru => {
+    describe(`Fallback - ${ru.text}`, () => {
+        const setup = createRouterTestSetup(ru.hash);
+        let cleanup: () => void;
+        beforeAll(() => {
+            cleanup = init({
+                implicitMode: ru.implicitMode,
+                hashMode: ru.hashMode,
+            });
+        });
+        afterAll(() => {
+            cleanup();
+        });
+        describe("Default Props", () => {
+            defaultPropsTests(setup);
+        });
+        describe("Explicit Props", () => {
+            explicitPropsTests(setup);
+        });
+        describe("Reactivity", () => {
+            reactivityTests(setup);
+        });
+    });
+});

src/lib/Fallback/Fallback.svelte.test.ts

@@ -1,7 +1,7 @@
 <script lang="ts" module>
 	import { RouterEngine } from '$lib/core/RouterEngine.svelte.js';
 	import { resolveHashValue } from '$lib/core/resolveHashValue.js';
-	import type { RouteStatus } from '$lib/types.js';
+	import type { Hash, RouteStatus } from '$lib/types.js';
 
 	const parentCtxKey = Symbol();
 	const hashParentCtxKey = Symbol();
@@ -15,10 +15,15 @@
 	 * @param hash Hash value that identifies the desired router context.
 	 * @returns The closest router context found for the specified hash, or `undefined` if there is none.
 	 */
-	export function getRouterContext(hash: boolean | string) {
-		return getContext<RouterEngine | undefined>(
-			typeof hash === 'string' ? multiHashSymbol(hash) : hash ? hashParentCtxKey : parentCtxKey
-		);
+	export function getRouterContext(hash: Hash) {
+		return getContext<RouterEngine | undefined>(getRouterContextKey(hash));
+	}
+
+	/**
+	 * Only exported for unit testing.
+	 */
+	export function getRouterContextKey(hash: Hash) {
+		return typeof hash === 'string' ? multiHashSymbol(hash) : hash ? hashParentCtxKey : parentCtxKey;
 	}
 
 	/**

src/lib/Router/Router.svelte

@@ -45,7 +45,7 @@ export { default as Link } from "$lib/Link/Link.svelte";
 export { default as LinkContext } from "$lib/LinkContext/LinkContext.svelte";
 export * from "$lib/Route/Route.svelte";
 export { default as Route } from "$lib/Route/Route.svelte";
-export * from "$lib/Router/Router.svelte";
+export { getRouterContext, setRouterContext } from "$lib/Router/Router.svelte";
 export { default as Router } from "$lib/Router/Router.svelte";
 export * from "$lib/Fallback/Fallback.svelte";
 export { default as Fallback } from "$lib/Fallback/Fallback.svelte";

src/lib/index.ts

@@ -0,0 +1,113 @@
+import { type Hash } from "$lib/index.js";
+import { RouterEngine } from "$lib/core/RouterEngine.svelte.js";
+import { getRouterContextKey } from "../Router/Router.svelte";
+import { createRawSnippet } from "svelte";
+import type { RoutingOptions } from "$lib/core/options.js";
+import { resolveHashValue } from "$lib/core/resolveHashValue.js";
+
+/**
+ * Standard routing universe test configurations
+ */
+export const ROUTING_UNIVERSES: {
+    hash: Hash | undefined;
+    implicitMode: RoutingOptions['implicitMode'];
+    hashMode: Exclude<RoutingOptions['hashMode'], undefined>;
+    text: string;
+    name: string;
+}[] = [
+    { hash: undefined, implicitMode: 'path', hashMode: 'single', text: "IMP", name: "Implicit Path Routing" },
+    { hash: undefined, implicitMode: 'hash', hashMode: 'single', text: "IMH", name: "Implicit Hash Routing" },
+    { hash: false, implicitMode: 'path', hashMode: 'single', text: "PR", name: "Path Routing" },
+    { hash: true, implicitMode: 'path', hashMode: 'single', text: "HR", name: "Hash Routing" },
+    { hash: 'p1', implicitMode: 'path', hashMode: 'multi', text: "MHR", name: "Multi Hash Routing" },
+] as const;
+
+/**
+ * Creates a router and context setup for testing
+ */
+export function createRouterTestSetup(hash: Hash | undefined) {
+    let router: RouterEngine | undefined;
+    let context: Map<any, any>;
+    
+    const init = () => {
+        // Dispose previous router if it exists
+        router?.dispose();
+        
+        // Create fresh router and context for each test
+        router = new RouterEngine({ hash });
+        context = new Map();
+        context.set(getRouterContextKey(resolveHashValue(hash)), router);
+    };
+    
+    const dispose = () => {
+        router?.dispose();
+        router = undefined;
+        context = new Map();
+    };
+    
+    return {
+        get hash() { return hash; },
+        get router() { 
+            if (!router) throw new Error('Router not initialized. Call init() first.');
+            return router; 
+        },
+        get context() { 
+            if (!context) throw new Error('Context not initialized. Call init() first.');
+            return context; 
+        },
+        init,
+        dispose
+    };
+}
+
+/**
+ * Creates a test snippet with the given content
+ */
+export function createTestSnippet(contentText: string) {
+    return createRawSnippet(() => {
+        return {
+            render: () => `<div>${contentText}</div>`
+        };
+    });
+}
+
+/**
+ * Generates a new random route key
+ */
+export function newRandomRouteKey() {
+    return `route-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Adds a matching route to the router
+ */
+export function addMatchingRoute(router: RouterEngine, routeName?: string) {
+    routeName ||= newRandomRouteKey();
+    router.routes[routeName] = {
+        and: () => true
+    };
+    return routeName;
+}
+
+/**
+ * Adds a non-matching route to the router
+ */
+export function addNonMatchingRoute(router: RouterEngine, routeName?: string) {
+    routeName ||= newRandomRouteKey();
+    router.routes[routeName] = {
+        and: () => false
+    };
+    return routeName;
+}
+
+export function addRoutes(router: RouterEngine, routes: { matching?: number; nonMatching?: number; }) {
+    const { matching = 0, nonMatching = 0 } = routes;
+    const routeNames = [];
+    for (let i = 0; i < matching; i++) {
+        routeNames.push(addMatchingRoute(router));
+    }
+    for (let i = 0; i < nonMatching; i++) {
+        routeNames.push(addNonMatchingRoute(router));
+    }
+    return routeNames;
+}