@wavelengthusaf/client-router 0.0.1

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

@@ -0,0 +1,89 @@
+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

@@ -0,0 +1,253 @@
+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

@@ -0,0 +1,15 @@
+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

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

package/src/models/MatchedRoute.ts

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

package/src/models/RouteComponent.ts

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

package/src/models/RouteContext.ts

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

package/src/models/RouteDefinition.ts

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

package/src/models/RouteGuard.ts

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

package/src/models/RouteParams.ts

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

package/src/models/index.ts

@@ -0,0 +1,17 @@
+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,
+};

package/src/router/Router.ts

@@ -0,0 +1,225 @@
+import type {
+  CompiledRoute,
+  MatchedRoute,
+  RouteComponent,
+  RouteContext,
+  RouteDefinition,
+  RouteGuard,
+} from '../models/index.ts';
+import { compileRoute, matchRoute } from '../utils/index.ts';
+
+export interface RouterEnv {
+  window?: Window;
+  document?: Document;
+}
+
+export interface RouterOptions {
+  outlet?: HTMLElement;
+  hashMode?: boolean;
+  beforeEach?: RouteGuard;
+}
+
+export class Router {
+  readonly #compiledRoutes: CompiledRoute[];
+  readonly #hashMode: boolean;
+  readonly #outlet: HTMLElement | undefined;
+  readonly #beforeEach?: RouteGuard;
+  #currentComponent?: RouteComponent;
+  readonly #window?: Window;
+  readonly #document?: Document;
+
+  #isStarted: boolean = false;
+
+  constructor(
+    routeDefinitions: RouteDefinition[],
+    routerOptions: RouterOptions = {},
+    env: RouterEnv = {},
+  ) {
+    this.#compiledRoutes = routeDefinitions.map(compileRoute);
+    this.#hashMode = routerOptions.hashMode ?? false;
+
+    if (routerOptions.beforeEach !== undefined) {
+      this.#beforeEach = routerOptions.beforeEach;
+    }
+
+    if (env.window !== undefined) {
+      this.#window = env.window;
+    }
+
+    if (env.document !== undefined) {
+      this.#document = env.document;
+    }
+
+    this.#outlet = routerOptions.outlet ?? this.#document?.body ?? undefined;
+  }
+
+  public start(): void {
+    if (!this.#window?.addEventListener || !this.#document?.addEventListener) {
+      throw new Error('[Router] Invalid environment: missing DOM APIs');
+    }
+
+    if (this.#isStarted) return;
+
+    this.#bindEvents();
+    this.#resolve();
+
+    this.#isStarted = true;
+  }
+
+  public destroy(): void {
+    if (!this.#window || !this.#document) return;
+
+    this.#window.removeEventListener('popstate', this.#handlePopState);
+    this.#document.removeEventListener('click', this.#handleClick);
+
+    this.#currentComponent?.unmount?.();
+    this.#isStarted = false;
+  }
+
+  public navigate(path: string): void {
+    if (!this.#window) return;
+
+    if (this.#hashMode) {
+      this.#window.location.hash = path;
+    } else {
+      this.#window.history.pushState(null, '', path);
+    }
+
+    this.#resolve();
+  }
+
+  public replace(path: string): void {
+    if (!this.#window) return;
+
+    if (this.#hashMode) {
+      this.#window.location.replace('#' + path);
+    } else {
+      this.#window.history.replaceState(null, '', path);
+    }
+
+    this.#resolve();
+  }
+
+  public back(): void {
+    this.#window?.history.back();
+  }
+
+  #bindEvents(): void {
+    this.#window!.addEventListener('popstate', this.#handlePopState);
+    this.#document!.addEventListener('click', this.#handleClick);
+  }
+
+  #handlePopState = (): void => {
+    this.#resolve();
+  };
+
+  #handleClick = (event: MouseEvent): void => {
+    const target = event.target as Element | null;
+    const anchor = target?.closest?.('a') as HTMLAnchorElement | null;
+
+    if (!anchor) return;
+
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+      return;
+
+    if (anchor.target === '_blank') return;
+
+    const href: string | null = anchor.getAttribute('href');
+
+    if (!href) return;
+
+    if (
+      href.startsWith('http') ||
+      href.startsWith('//') ||
+      href.startsWith('mailto:') ||
+      href.startsWith('tel:')
+    ) {
+      return;
+    }
+
+    event.preventDefault();
+    this.navigate(href);
+  };
+
+  #currentPath(): string {
+    if (!this.#window) return '/';
+
+    if (this.#hashMode) {
+      const hash: string = this.#window.location.hash.slice(1);
+      return hash || '/';
+    }
+
+    return this.#window.location.pathname || '/';
+  }
+
+  #currentQuery(): URLSearchParams {
+    if (!this.#window) return new URLSearchParams();
+
+    if (this.#hashMode) {
+      const hash = this.#window.location.hash;
+      const queryIndex = hash.indexOf('?');
+
+      if (queryIndex >= 0) {
+        return new URLSearchParams(hash.slice(queryIndex));
+      }
+
+      return new URLSearchParams();
+    }
+
+    return new URLSearchParams(this.#window.location.search);
+  }
+
+  #mount(routeComponent: RouteComponent, routeContext: RouteContext): void {
+    if (!this.#outlet) return;
+
+    this.#currentComponent?.unmount?.();
+
+    this.#outlet.replaceChildren();
+
+    routeComponent.mount(this.#outlet, routeContext);
+
+    this.#currentComponent = routeComponent;
+  }
+
+  #resolve(): void {
+    const pathname: string = this.#currentPath();
+    const query: URLSearchParams = this.#currentQuery();
+
+    const match: MatchedRoute | null = matchRoute(
+      this.#compiledRoutes,
+      pathname,
+    );
+
+    if (!match) {
+      console.warn(`[Router] No route matched: ${pathname}`);
+      return;
+    }
+
+    const context: RouteContext = {
+      path: pathname,
+      routeParams: match.routeParams,
+      query,
+    };
+
+    if (!this.#beforeEach) {
+      this.#mount(match.routeDefinition.routeComponent, context);
+      return;
+    }
+
+    let redirected: boolean = false;
+
+    const next = (redirect?: string): void => {
+      if (redirected) return;
+
+      redirected = true;
+
+      if (redirect && redirect !== context.path) {
+        this.navigate(redirect);
+      } else {
+        this.#mount(match.routeDefinition.routeComponent, context);
+      }
+    };
+
+    this.#beforeEach(context, next);
+  }
+}