@wavelengthusaf/client-router 0.0.1 → 0.0.2

package/src/elements/RouterElement.ts

@@ -1,97 +0,0 @@
-import type { RouteDefinition, RouteGuard } from '../models/index.ts';
-import { Router } from '../router/Router.ts';
-import type { RouteElement } from './RouteElement.ts';
-
-export class RouterElement extends HTMLElement {
-  public static readonly tag = 'wavelength-router';
-
-  #router?: Router;
-
-  public static get observedAttributes(): string[] {
-    return ['hash-mode', 'guard'];
-  }
-
-  public connectedCallback(): void {
-    this.#bootstrap();
-  }
-
-  public disconnectedCallback(): void {
-    this.#teardown();
-  }
-
-  public attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void {
-    if (!this.isConnected || oldValue === newValue) return;
-    this.#bootstrap();
-  }
-
-  public navigate(path: string): void {
-    this.#router?.navigate(path);
-  }
-
-  public replace(path: string): void {
-    this.#router?.replace(path);
-  }
-
-  public back(): void {
-    this.#router?.back();
-  }
-
-  #bootstrap(): void {
-    this.#teardown();
-
-    const routes: RouteDefinition[] = this.#collectRoutes();
-
-    if (routes.length === 0) {
-      console.warn('[wavelength-router] No <wavelength-route> children found.');
-      return;
-    }
-
-    const guard: RouteGuard | undefined =this.#resolveGuard();
-    this.#router = new Router(
-        routes,
-        {
-          outlet: this,
-          hashMode: this.hasAttribute('hash-mode'),
-          ...(guard ? { beforeEach: guard } : {}),
-        },
-        {
-          window: window,
-          document: document,
-        },
-    );
-
-    this.#router.start();
-  }
-
-  #teardown(): void {
-    this.#router?.destroy();
-  }
-
-  #collectRoutes(): RouteDefinition[] {
-    const routeElements: RouteElement[] = Array.from(
-        this.querySelectorAll<RouteElement>('wavelength-route'),
-    );
-
-    return routeElements
-        .map((routeElement: RouteElement) => routeElement.toDefinition({ document }))
-        .filter((routeDefinition: RouteDefinition | null): routeDefinition is RouteDefinition => routeDefinition !== null);
-  }
-
-  #resolveGuard(): RouteGuard | undefined {
-    const guardName: string | null = this.getAttribute('guard');
-    if (!guardName) return undefined;
-
-    const fn: unknown = (window as unknown as Record<string, unknown>)[guardName];
-
-    if (typeof fn !== 'function') {
-      console.warn(`[wavelength-router] Guard "${guardName}" not found on window.`);
-      return undefined;
-    }
-
-    return fn as RouteGuard;
-  }
-}
-
-if (!customElements.get(RouterElement.tag)) {
-  customElements.define(RouterElement.tag, RouterElement);
-}

package/src/elements/__tests__/RouteElement.test.ts

@@ -1,89 +0,0 @@
-import { describe, expect, it, vi, beforeEach } from 'vitest';
-import { RouteElement } from '../RouteElement.ts';
-
-/* eslint-disable  @typescript-eslint/no-explicit-any */
-describe('RouteElement', () => {
-    beforeEach(() => {
-        if (!customElements.get(RouteElement.tag)) {
-            customElements.define(RouteElement.tag, RouteElement);
-        }
-        document.body.innerHTML = '';
-    });
-
-    describe('Attribute Accessors & toDefinition Logic', () => {
-        it.each([
-            {
-                it: 'returns default path "*" if attribute is missing',
-                html: `<wavelength-route component="my-view"></wavelength-route>`,
-                expectedPath: '*',
-                expectedTag: 'my-view'
-            },
-            {
-                it: 'extracts specified path and component tag',
-                html: `<wavelength-route path="/home" component="home-view"></wavelength-route>`,
-                expectedPath: '/home',
-                expectedTag: 'home-view'
-            },
-            {
-                it: 'returns null and warns if component attribute is missing',
-                html: `<wavelength-route path="/error"></wavelength-route>`,
-                expectedPath: '/error',
-                expectedTag: '',
-                shouldBeNull: true
-            }
-        ])('$it', ({ html, expectedPath, expectedTag, shouldBeNull }) => {
-            document.body.innerHTML = html;
-            const el = document.querySelector<RouteElement>('wavelength-route')!;
-            const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-            expect(el.path).toBe(expectedPath);
-            expect(el.componentTag).toBe(expectedTag);
-
-            const def = el.toDefinition({ document });
-
-            if (shouldBeNull) {
-                expect(def).toBeNull();
-                expect(warnSpy).toHaveBeenCalled();
-            } else {
-                expect(def?.path).toBe(expectedPath);
-                expect(def?.routeComponent).toBeDefined();
-            }
-
-            warnSpy.mockRestore();
-        });
-    });
-
-    describe('SSR / Environment Resilience', () => {
-        it('returns a no-op component if document is missing', () => {
-            const el = document.createElement('wavelength-route') as RouteElement;
-            el.setAttribute('component', 'test-view');
-
-            const def = el.toDefinition({});
-
-            expect(def?.path).toBe('*');
-            expect(def?.routeComponent.mount).toBeInstanceOf(Function);
-            expect(() => def?.routeComponent.mount({} as any, {} as any)).not.toThrow();
-            expect(() => def?.routeComponent.unmount?.()).not.toThrow();
-        });
-    });
-
-    describe('RouteComponent Mounting Logic', () => {
-        it('properly creates element and injects context on mount', () => {
-            const el = document.createElement('wavelength-route') as RouteElement;
-            el.setAttribute('component', 'user-profile');
-
-            const def = el.toDefinition({ document });
-            const container = document.createElement('div');
-            const mockContext = { path: '/user/1', routeParams: { id: '1' }, query: new URLSearchParams() };
-
-            def?.routeComponent.mount(container, mockContext as any);
-
-            const renderedElement = container.querySelector('user-profile') as any;
-
-            expect(renderedElement).toBeDefined();
-            expect(renderedElement.routeContext).toEqual(mockContext);
-            expect(def?.routeComponent.unmount).toBeDefined();
-            def?.routeComponent.unmount?.();
-        });
-    });
-});

package/src/elements/__tests__/RouterElement.test.ts

@@ -1,253 +0,0 @@
-import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
-import { RouterElement } from '../RouterElement.ts';
-import type { RouteElement } from '../RouteElement.ts';
-
-/* eslint-disable  @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-member-accessibility */
-const routerInstances: any[] = [];
-const routerArgs: any[] = [];
-
-vi.mock('../../router/Router.ts', () => {
-    return {
-        Router: class {
-            start = vi.fn();
-            destroy = vi.fn();
-            navigate = vi.fn();
-            replace = vi.fn();
-            back = vi.fn();
-
-            constructor(...args: any[]) {
-                routerInstances.push(this);
-                routerArgs.push(args);
-            }
-        },
-    };
-});
-
-const createFakeRoute = (def: any | null): RouteElement => {
-    const el = document.createElement('wavelength-route') as unknown as RouteElement;
-    el.toDefinition = vi.fn().mockReturnValue(def);
-    return el;
-};
-
-const setWindowProp = (key: string, value: any) => {
-    (window as any)[key] = value;
-    return () => delete (window as any)[key];
-};
-
-describe('RouterElement', () => {
-    let container: HTMLDivElement;
-    let warnSpy: ReturnType<typeof vi.spyOn>;
-
-    beforeEach(() => {
-        container = document.createElement('div');
-        document.body.appendChild(container);
-
-        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
-
-        routerInstances.length = 0;
-        routerArgs.length = 0;
-
-        vi.clearAllMocks();
-    });
-
-    afterEach(() => {
-        document.body.innerHTML = '';
-        warnSpy.mockRestore();
-    });
-
-    describe('Lifecycle & Bootstrapping', () => {
-        it('warns and aborts if no route children are found', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-
-            container.appendChild(el);
-
-            expect(warnSpy).toHaveBeenCalledWith(
-                '[wavelength-router] No <wavelength-route> children found.',
-            );
-            expect(routerInstances).toHaveLength(0);
-        });
-
-        it('filters out invalid route definitions', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-
-            el.appendChild(createFakeRoute({ path: '/valid', routeComponent: {} }));
-            el.appendChild(createFakeRoute(null));
-
-            container.appendChild(el);
-
-            expect(routerInstances).toHaveLength(1);
-
-            const [routes] = routerArgs[0];
-            expect(routes).toHaveLength(1);
-            expect(routes[0]!.path).toBe('/valid');
-        });
-
-        it('starts the router after bootstrap', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            expect(routerInstances[0].start).toHaveBeenCalled();
-        });
-
-        it('tears down the router on disconnectedCallback', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            const instance = routerInstances[0];
-
-            container.removeChild(el);
-
-            expect(instance.destroy).toHaveBeenCalled();
-        });
-
-        it('destroys existing router if routes become empty on re-bootstrap', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            const first = routerInstances[0];
-
-            el.innerHTML = '';
-            el.setAttribute('hash-mode', '');
-
-            expect(first.destroy).toHaveBeenCalled();
-            expect(routerInstances).toHaveLength(1);
-        });
-    });
-
-    describe('Attribute Reactions & Re-bootstrapping', () => {
-        it('ignores attribute changes if not connected to the DOM', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-
-            el.attributeChangedCallback('hash-mode', null, '');
-
-            expect(routerInstances).toHaveLength(0);
-        });
-
-        it('re-bootstraps when observed attributes change', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            const first = routerInstances[0];
-
-            el.setAttribute('hash-mode', '');
-
-            expect(first.destroy).toHaveBeenCalled();
-            expect(routerInstances.length).toBeGreaterThan(1);
-
-            const [, options] = routerArgs[1];
-            expect(options.hashMode).toBe(true);
-        });
-    });
-
-    describe('Guard Resolution Table', () => {
-        it.each([
-            {
-                it: 'returns undefined if guard attribute is missing',
-                setup: () => {},
-                guardAttr: null,
-                expectedWarn: false,
-                expectGuard: false,
-            },
-            {
-                it: 'warns if guard is not found on window',
-                setup: () => {},
-                guardAttr: 'missingGuard',
-                expectedWarn: true,
-                expectGuard: false,
-            },
-            {
-                it: 'warns if guard is not a function',
-                setup: () => setWindowProp('notAFunc', 'string'),
-                guardAttr: 'notAFunc',
-                expectedWarn: true,
-                expectGuard: false,
-            },
-            {
-                it: 'resolves and passes valid guard',
-                setup: () => setWindowProp('validGuard', vi.fn()),
-                guardAttr: 'validGuard',
-                expectedWarn: false,
-                expectGuard: true,
-            },
-        ])('$it', ({ setup, guardAttr, expectedWarn, expectGuard }) => {
-            const cleanup = setup?.();
-
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-
-            if (guardAttr) el.setAttribute('guard', guardAttr);
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            if (expectedWarn) {
-                expect(warnSpy).toHaveBeenCalledWith(
-                    expect.stringContaining('[wavelength-router] Guard'),
-                );
-            } else {
-                expect(warnSpy).not.toHaveBeenCalled();
-            }
-
-            const [, options] = routerArgs[0];
-
-            if (expectGuard) {
-                expect(options.beforeEach).toBeDefined();
-            } else {
-                expect(options.beforeEach).toBeUndefined();
-            }
-
-            // @ts-expect-error (passing wrong parameters)
-            cleanup?.();
-        });
-    });
-
-    describe('Delegated Router Methods Table', () => {
-        it.each([
-            { method: 'navigate', args: ['/path'] },
-            { method: 'replace', args: ['/path'] },
-            { method: 'back', args: [] },
-        ] as const)(
-            'delegates $method to router safely',
-            ({ method, args }) => {
-                const el = document.createElement(RouterElement.tag) as RouterElement;
-
-                expect(() => (el[method] as any)(...args)).not.toThrow();
-
-                el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-                container.appendChild(el);
-
-                const instance = routerInstances[0];
-
-                (el[method] as any)(...args);
-
-                expect(instance[method]).toHaveBeenCalledWith(...args);
-            },
-        );
-    });
-
-    describe('Router constructor contract', () => {
-        it('passes correct options and environment', () => {
-            const el = document.createElement(RouterElement.tag) as RouterElement;
-
-            el.setAttribute('hash-mode', '');
-            el.appendChild(createFakeRoute({ path: '/', routeComponent: {} }));
-
-            container.appendChild(el);
-
-            const [, options, env] = routerArgs[0];
-
-            expect(options.outlet).toBe(el);
-            expect(options.hashMode).toBe(true);
-
-            expect(env.window).toBe(window);
-            expect(env.document).toBe(document);
-        });
-    });
-});

package/src/index.ts

@@ -1,15 +0,0 @@
-export { Router } from './router/Router.ts';
-export { RouterElement } from './elements/RouterElement.ts';
-export { RouteElement } from './elements/RouteElement.ts';
-
-export type {
-  RouteComponent,
-  RouteContext,
-  RouteDefinition,
-  RouteGuard,
-  RouteParams,
-  CompiledRoute,
-  MatchedRoute,
-} from './models/index.ts';
-
-export { compileRoute, matchRoute } from './utils/index.ts';

package/src/models/CompiledRoute.ts

@@ -1,7 +0,0 @@
-import type { RouteDefinition } from './RouteDefinition.js';
-
-export interface CompiledRoute {
-  routeDefinition: RouteDefinition;
-  pattern: RegExp;
-  paramNames: string[];
-}

package/src/models/MatchedRoute.ts

@@ -1,7 +0,0 @@
-import type { RouteDefinition } from './RouteDefinition.ts';
-import type { RouteParams } from './RouteParams.ts';
-
-export interface MatchedRoute {
-  routeDefinition: RouteDefinition;
-  routeParams: RouteParams;
-}

package/src/models/RouteComponent.ts

@@ -1,6 +0,0 @@
-import type { RouteContext } from './RouteContext.ts';
-
-export interface RouteComponent {
-  mount(container: HTMLElement, context: RouteContext): void;
-  unmount?(): void;
-}

package/src/models/RouteContext.ts

@@ -1,7 +0,0 @@
-import type { RouteParams } from './RouteParams.ts';
-
-export interface RouteContext {
-  path: string;
-  routeParams: RouteParams;
-  query: URLSearchParams;
-}

package/src/models/RouteDefinition.ts

@@ -1,6 +0,0 @@
-import type { RouteComponent } from './RouteComponent.ts';
-
-export interface RouteDefinition {
-  path: string;
-  routeComponent: RouteComponent;
-}

package/src/models/RouteGuard.ts

@@ -1,6 +0,0 @@
-import type { RouteContext } from './RouteContext.ts';
-
-export type RouteGuard = (
-  to: RouteContext,
-  next: (redirect?: string) => void,
-) => void;

package/src/models/RouteParams.ts

@@ -1,3 +0,0 @@
-export interface RouteParams {
-  [key: string]: string;
-}

package/src/models/index.ts

@@ -1,17 +0,0 @@
-import type { CompiledRoute } from './CompiledRoute.ts';
-import type { MatchedRoute } from './MatchedRoute.ts';
-import type { RouteComponent } from './RouteComponent.ts';
-import type { RouteContext } from './RouteContext.ts';
-import type { RouteDefinition } from './RouteDefinition.ts';
-import type { RouteGuard } from './RouteGuard.ts';
-import type { RouteParams } from './RouteParams.ts';
-
-export type {
-  CompiledRoute,
-  MatchedRoute,
-  RouteComponent,
-  RouteContext,
-  RouteDefinition,
-  RouteGuard,
-  RouteParams,
-};