@wavelengthusaf/client-router 0.0.1

package/src/stories/RouterElement.stories.test.ts

@@ -0,0 +1,310 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import * as stories from './RouterElement.stories.ts';
+
+vi.mock('../router/Router.ts', () => {
+  return {
+    Router: class MockRouter {
+      public static readonly instances: MockRouter[] = [];
+
+      public start = vi.fn();
+      public destroy = vi.fn();
+      public navigate = vi.fn();
+      public replace = vi.fn();
+      public back = vi.fn();
+
+      constructor() {
+        MockRouter.instances.push(this);
+      }
+    },
+  };
+});
+
+describe('RouterElement Stories', () => {
+  let container: HTMLDivElement;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    document.body.removeChild(container);
+    warnSpy.mockRestore();
+  });
+
+  describe('Story: Basic', () => {
+    it('renders router with two routes', () => {
+      const element = stories.Basic.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const router = container.querySelector('wavelength-router');
+      expect(router).not.toBeNull();
+
+      const routes = container.querySelectorAll('wavelength-route');
+      expect(routes).toHaveLength(2);
+    });
+
+    it('has correct route definitions', () => {
+      const element = stories.Basic.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const homeRoute = container.querySelector('wavelength-route[path="/"]');
+      const aboutRoute = container.querySelector(
+        'wavelength-route[path="/about"]',
+      );
+
+      expect(homeRoute?.getAttribute('component')).toBe('demo-home');
+      expect(aboutRoute?.getAttribute('component')).toBe('demo-about');
+    });
+
+    it('displays navigation links', () => {
+      const element = stories.Basic.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const links = container.querySelectorAll('nav a');
+      expect(links).toHaveLength(2);
+      expect(links[0]?.getAttribute('href')).toBe('/');
+      expect(links[1]?.getAttribute('href')).toBe('/about');
+    });
+
+    it('registers demo components', () => {
+      stories.Basic.render!();
+
+      expect(customElements.get('demo-home')).toBeDefined();
+      expect(customElements.get('demo-about')).toBeDefined();
+    });
+  });
+
+  describe('Story: HashMode', () => {
+    it('renders router with hash-mode attribute', () => {
+      const element = stories.HashMode.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const router = container.querySelector('wavelength-router[hash-mode]');
+      expect(router).not.toBeNull();
+    });
+
+    it('has correct routes for hash mode', () => {
+      const element = stories.HashMode.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const profileRoute = container.querySelector(
+        'wavelength-route[path="/profile"]',
+      );
+      expect(profileRoute?.getAttribute('component')).toBe('demo-profile-hash');
+    });
+
+    it('registers unique component tags', () => {
+      stories.HashMode.render!();
+
+      expect(customElements.get('demo-home-hash')).toBeDefined();
+      expect(customElements.get('demo-profile-hash')).toBeDefined();
+    });
+  });
+
+  describe('Story: WithGuard', () => {
+    it('renders router with guard attribute', () => {
+      const element = stories.WithGuard.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const router = container.querySelector(
+        'wavelength-router[guard="authGuard"]',
+      );
+      expect(router).not.toBeNull();
+    });
+
+    it('defines authGuard on window', () => {
+      stories.WithGuard.render!();
+
+      expect(
+        (window as unknown as Record<string, unknown>).authGuard,
+      ).toBeDefined();
+      expect(
+        typeof (window as unknown as Record<string, unknown>).authGuard,
+      ).toBe('function');
+    });
+
+    it('guard redirects /protected to /login', () => {
+      stories.WithGuard.render!();
+
+      const authGuard = (window as unknown as Record<string, unknown>)
+        .authGuard as (
+        ctx: { path: string },
+        next: (redirect?: string) => void,
+      ) => void;
+
+      let redirectedTo: string | undefined;
+
+      authGuard({ path: '/protected' }, (redirect) => {
+        redirectedTo = redirect;
+      });
+
+      expect(redirectedTo).toBe('/login');
+    });
+
+    it('guard allows non-protected routes', () => {
+      stories.WithGuard.render!();
+
+      const authGuard = (window as unknown as Record<string, unknown>)
+        .authGuard as (
+        ctx: { path: string },
+        next: (redirect?: string) => void,
+      ) => void;
+
+      let redirectedTo: string | undefined;
+
+      authGuard({ path: '/about' }, (redirect) => {
+        redirectedTo = redirect;
+      });
+
+      expect(redirectedTo).toBeUndefined();
+    });
+  });
+
+  describe('Story: ProgrammaticNavigation', () => {
+    it('renders router with navigation button', () => {
+      const element = stories.ProgrammaticNavigation
+        .render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const button = container.querySelector('#go-next');
+      expect(button).not.toBeNull();
+      expect(button?.textContent).toBe('Go to Next');
+    });
+
+    it('router element has navigate method', () => {
+      const element = stories.ProgrammaticNavigation
+        .render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const router = container.querySelector(
+        'wavelength-router',
+      ) as HTMLElement & {
+        navigate(path: string): void;
+      };
+
+      expect(typeof router.navigate).toBe('function');
+    });
+
+    it('button click handler is attached', () => {
+      const element = stories.ProgrammaticNavigation
+        .render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const button = container.querySelector('#go-next') as HTMLButtonElement;
+      const router = container.querySelector(
+        'wavelength-router',
+      ) as HTMLElement & {
+        navigate(path: string): void;
+      };
+
+      const navigateSpy = vi.spyOn(router, 'navigate');
+
+      button.click();
+
+      expect(navigateSpy).toHaveBeenCalledWith('/next');
+    });
+  });
+
+  describe('Story: WithRouteParams', () => {
+    it('renders router with parameterized route', () => {
+      const element = stories.WithRouteParams.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const paramRoute = container.querySelector(
+        'wavelength-route[path="/users/:userId"]',
+      );
+      expect(paramRoute).not.toBeNull();
+    });
+
+    it('has wildcard route for 404', () => {
+      const element = stories.WithRouteParams.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const wildcardRoute = container.querySelector(
+        'wavelength-route[path="*"]',
+      );
+      expect(wildcardRoute).not.toBeNull();
+    });
+
+    it('has navigation links with route params', () => {
+      const element = stories.WithRouteParams.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const links = container.querySelectorAll('nav a');
+      expect(links[0]?.getAttribute('href')).toBe('/users/123');
+      expect(links[1]?.getAttribute('href')).toBe('/users/456');
+    });
+  });
+
+  describe('Story: NoMatch', () => {
+    it('renders router with wildcard route', () => {
+      const element = stories.NoMatch.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const wildcardRoute = container.querySelector(
+        'wavelength-route[path="*"]',
+      );
+      expect(wildcardRoute).not.toBeNull();
+    });
+
+    it('has link to non-existent route', () => {
+      const element = stories.NoMatch.render!() as DocumentFragment;
+      container.appendChild(element as unknown as Node);
+
+      const link = container.querySelector('a[href="/does-not-exist"]');
+      expect(link?.textContent).toBe('Broken Route');
+    });
+
+    it('does not warn about missing routes (wildcard present)', () => {
+      stories.NoMatch.render!();
+
+      expect(warnSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('No <wavelength-route> children found'),
+      );
+    });
+  });
+
+  describe('Story isolation', () => {
+    it('each story creates unique component tags', () => {
+      stories.Basic.render!();
+      stories.HashMode.render!();
+      stories.WithGuard.render!();
+
+      expect(customElements.get('demo-home')).toBeDefined();
+      expect(customElements.get('demo-home-hash')).toBeDefined();
+      expect(customElements.get('demo-home-guard')).toBeDefined();
+    });
+
+    it('stories can be rendered multiple times without errors', () => {
+      expect(() => {
+        const el1 = stories.Basic.render!() as DocumentFragment;
+        const el2 = stories.Basic.render!() as DocumentFragment;
+        container.appendChild(el1 as unknown as Node);
+        container.appendChild(el2 as unknown as Node);
+      }).not.toThrow();
+    });
+  });
+
+  describe('Story metadata', () => {
+    it('meta has correct title', () => {
+      expect(stories.default.title).toBe('Router/RouterElement');
+    });
+
+    it('meta references wavelength-router component', () => {
+      expect(stories.default.component).toBe('wavelength-router');
+    });
+
+    it('all stories are exported', () => {
+      expect(stories.Basic).toBeDefined();
+      expect(stories.HashMode).toBeDefined();
+      expect(stories.WithGuard).toBeDefined();
+      expect(stories.ProgrammaticNavigation).toBeDefined();
+      expect(stories.WithRouteParams).toBeDefined();
+      expect(stories.NoMatch).toBeDefined();
+    });
+  });
+});

package/src/stories/RouterElement.stories.ts

@@ -0,0 +1,208 @@
+import type { Meta, StoryObj } from '@storybook/web-components-vite';
+
+import '../elements/RouteElement.ts';
+import '../elements/RouterElement.ts';
+
+const meta: Meta = {
+  title: 'Router/RouterElement',
+  component: 'wavelength-router',
+  tags: ['autodocs'],
+};
+
+export default meta;
+
+type Story = StoryObj;
+
+interface DemoPageProperties {
+  title: string;
+  content?: string;
+}
+
+function createDemoPage(
+  tag: string,
+  { title, content }: DemoPageProperties,
+): void {
+  if (customElements.get(tag)) return;
+
+  customElements.define(
+    tag,
+    class DemoPage extends HTMLElement {
+      public connectedCallback() {
+        this.textContent = content ?? title;
+      }
+    },
+  );
+}
+
+function createRouterContainer(
+  routes: { path: string; component: string }[],
+): string {
+  const routeElements = routes
+    .map(
+      (r) =>
+        `<wavelength-route path="${r.path}" component="${r.component}"></wavelength-route>`,
+    )
+    .join('\n        ');
+
+  return `
+        <wavelength-router>
+            ${routeElements}
+        </wavelength-router>
+    `;
+}
+
+export const Basic: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    createDemoPage('demo-home', { title: 'Home Page' });
+    createDemoPage('demo-about', { title: 'About Page' });
+
+    container.innerHTML = `
+            ${createRouterContainer([
+              { path: '/', component: 'demo-home' },
+              { path: '/about', component: 'demo-about' },
+            ])}
+            <nav style="margin-top: 16px;">
+                <a href="/">Home</a>
+                <a href="/about" style="margin-left: 8px;">About</a>
+            </nav>
+        `;
+
+    return container;
+  },
+};
+
+export const HashMode: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    createDemoPage('demo-home-hash', { title: 'Home Page' });
+    createDemoPage('demo-profile-hash', { title: 'Profile Page' });
+
+    container.innerHTML = `
+            <wavelength-router hash-mode>
+                <wavelength-route path="/" component="demo-home-hash"></wavelength-route>
+                <wavelength-route path="/profile" component="demo-profile-hash"></wavelength-route>
+            </wavelength-router>
+            <nav style="margin-top: 16px;">
+                <a href="#/profile">Go to Profile</a>
+            </nav>
+        `;
+
+    return container;
+  },
+};
+
+export const WithGuard: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    type NextCallback = (redirect?: string) => void;
+
+    (window as unknown as Record<string, unknown>).authGuard = (
+      ctx: { path: string },
+      next: NextCallback,
+    ): void => {
+      if (ctx.path === '/protected') {
+        next('/login');
+      } else {
+        next();
+      }
+    };
+
+    createDemoPage('demo-home-guard', { title: 'Home Page' });
+    createDemoPage('demo-protected', { title: 'Protected Page' });
+    createDemoPage('demo-login', { title: 'Login Page' });
+
+    container.innerHTML = `
+            <wavelength-router guard="authGuard">
+                <wavelength-route path="/" component="demo-home-guard"></wavelength-route>
+                <wavelength-route path="/protected" component="demo-protected"></wavelength-route>
+                <wavelength-route path="/login" component="demo-login"></wavelength-route>
+            </wavelength-router>
+            <nav style="margin-top: 16px;">
+                <a href="/protected">Try Protected Route</a>
+            </nav>
+        `;
+
+    return container;
+  },
+};
+
+export const ProgrammaticNavigation: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    createDemoPage('demo-home-nav', { title: 'Home Page' });
+    createDemoPage('demo-next', { title: 'Next Page' });
+
+    container.innerHTML = `
+            ${createRouterContainer([
+              { path: '/', component: 'demo-home-nav' },
+              { path: '/next', component: 'demo-next' },
+            ])}
+            <button id="go-next">Go to Next</button>
+        `;
+
+    const button = container.querySelector('#go-next');
+    const router = container.querySelector(
+      'wavelength-router',
+    ) as HTMLElement & {
+      navigate(path: string): void;
+    };
+
+    if (button && router) {
+      button.addEventListener('click', () => {
+        router.navigate('/next');
+      });
+    }
+
+    return container;
+  },
+};
+
+export const WithRouteParams: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    createDemoPage('demo-user', { title: 'User Page' });
+    createDemoPage('demo-404', { title: 'Not Found' });
+
+    container.innerHTML = `
+            ${createRouterContainer([
+              { path: '/', component: 'demo-user' },
+              { path: '/users/:userId', component: 'demo-user' },
+              { path: '*', component: 'demo-404' },
+            ])}
+            <nav style="margin-top: 16px;">
+                <a href="/users/123">User 123</a>
+                <a href="/users/456" style="margin-left: 8px;">User 456</a>
+                <a href="/unknown" style="margin-left: 8px;">404</a>
+            </nav>
+        `;
+
+    return container;
+  },
+};
+
+export const NoMatch: Story = {
+  render: () => {
+    const container = document.createElement('div');
+
+    createDemoPage('demo-home-nomatch', { title: 'Home Page' });
+    createDemoPage('demo-notfound', { title: 'Page Not Found' });
+
+    container.innerHTML = `
+            ${createRouterContainer([
+              { path: '/', component: 'demo-home-nomatch' },
+              { path: '*', component: 'demo-notfound' },
+            ])}
+            <nav style="margin-top: 16px;">
+                <a href="/does-not-exist">Broken Route</a>
+            </nav>
+        `;
+
+    return container;
+  },
+};

package/src/utils/__tests__/compileRoute.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import { compileRoute } from '../compileRoute.ts';
+
+describe('compileRoute', () => {
+describe('static routes', () => {
+    it.each([
+        '/home',
+        '/about',
+        '/users/list',
+    ])('compiles %s correctly', (path) => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path });
+
+        expect(result.paramNames).toEqual([]);
+        expect(result.pattern.test(path)).toBe(true);
+    });
+});
+
+describe('param routes', () => {
+    it.each([
+        {
+            path: '/users/:id',
+            test: '/users/123',
+            params: ['id'],
+        },
+        {
+            path: '/posts/:postId/comments/:commentId',
+            test: '/posts/1/comments/99',
+            params: ['postId', 'commentId'],
+        },
+    ])('compiles $path', ({ path, test, params }) => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path });
+
+        expect(result.paramNames).toEqual(params);
+        expect(result.pattern.test(test)).toBe(true);
+    });
+});
+
+describe('wildcard', () => {
+    it.each([
+        '/',
+        '/anything',
+        '/deep/nested/path',
+    ])('matches all for * route', (test) => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path: '*' });
+
+        expect(result.paramNames).toEqual([]);
+        expect(result.pattern.test(test)).toBe(true);
+    });
+});
+
+describe('edge cases', () => {
+    it.each([
+        '/users/:id/',
+        '/users/:id/profile',
+        '/a/:b/c/:d/e',
+    ])('handles %s correctly', (path) => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path });
+
+        expect(result.pattern).toBeInstanceOf(RegExp);
+        expect(result.paramNames.length).toBeGreaterThan(0);
+    });
+});
+
+describe('regex safety', () => {
+    it('escapes special characters', () => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path: '/user.(test)' });
+
+        expect(result.pattern.test('/user.(test)')).toBe(true);
+    });
+});
+
+describe('strict matching', () => {
+    it('does not match partial paths', () => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({ path: '/users/:id' });
+
+        expect(result.pattern.test('/users/123/extra')).toBe(false);
+        expect(result.pattern.test('/users')).toBe(false);
+    });
+});
+
+describe('param extraction', () => {
+    it('preserves param order', () => {
+        // @ts-expect-error (passing wrong parameters)
+        const result = compileRoute({
+            path: '/a/:first/b/:second/c/:third',
+        });
+
+        expect(result.paramNames).toEqual(['first', 'second', 'third']);
+    });
+});
+});