@wavelengthusaf/client-router 0.0.1

package/eslint.config.mjs

@@ -0,0 +1,89 @@
+import prettier from 'eslint-config-prettier';
+import sonarjs from 'eslint-plugin-sonarjs';
+import storybook from 'eslint-plugin-storybook';
+import wc from 'eslint-plugin-wc';
+import globals from 'globals';
+import tsEslint from 'typescript-eslint';
+
+export default tsEslint.config(
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**', '.storybook/**'],
+  },
+
+  ...tsEslint.configs.recommended,
+  sonarjs.configs.recommended,
+
+  {
+    files: ['src/**/*.ts'],
+    plugins: {
+      wc,
+    },
+    languageOptions: {
+      parser: tsEslint.parser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        ...globals.browser,
+        ...globals.node,
+      },
+    },
+    rules: {
+      '@typescript-eslint/explicit-member-accessibility': [
+        'error',
+        {
+          accessibility: 'explicit',
+          overrides: {
+            constructors: 'no-public',
+          },
+        },
+      ],
+      '@typescript-eslint/consistent-type-exports': 'error',
+      '@typescript-eslint/no-import-type-side-effects': 'error',
+      '@typescript-eslint/no-explicit-any': 'error',
+
+      ...wc.configs.recommended.rules,
+
+      'wc/no-constructor-attributes': 'error',
+      'wc/no-invalid-element-name': 'error',
+      'wc/guard-super-call': 'error',
+      'wc/attach-shadow-constructor': 'off',
+      'wc/no-self-class': 'off',
+
+      'sonarjs/todo-tag': 'warn',
+      'sonarjs/no-selector-parameter': 'off',
+    },
+  },
+
+  {
+    files: ['**/*.test.ts', '**/*.spec.ts', 'src/**/*.stories.ts'],
+    languageOptions: {
+      parserOptions: {
+        projectService: {
+          allowDefaultProject: ['*.ts', '*.tsx'],
+          extendedReports: true,
+        },
+        tsconfigRootDir: import.meta.dirname,
+      },
+      globals: {
+        ...globals.node,
+        Bun: 'readonly',
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        test: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+      },
+    },
+    rules: {
+      '@typescript-eslint/no-unused-expressions': 'error',
+    },
+  },
+
+  ...storybook.configs['flat/recommended'],
+  prettier,
+);

package/index.ts

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

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@wavelengthusaf/client-router",
+  "version": "0.0.1",
+  "description": "Native TypeScript Router",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prettier": "prettier --write .",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "test-storybook": "test-storybook",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "router"
+  ],
+  "author": "Wavelength",
+  "license": "ISC",
+  "type": "module",
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.9.0",
+    "@storybook/addon-a11y": "^10.3.5",
+    "@storybook/addon-docs": "^10.3.5",
+    "@storybook/addon-links": "^10.3.5",
+    "@storybook/addon-vitest": "^10.3.5",
+    "@storybook/testing-library": "^0.2.1",
+    "@storybook/web-components": "^10.3.5",
+    "@storybook/web-components-vite": "^10.3.5",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/jsdom": "^28.0.1",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sonarjs": "^4.0.2",
+    "eslint-plugin-storybook": "^10.3.5",
+    "eslint-plugin-wc": "^3.1.0",
+    "globals": "^17.5.0",
+    "husky": "^9.1.7",
+    "jsdom": "^29.0.2",
+    "opencode-ai": "^1.4.6",
+    "playwright": "^1.59.1",
+    "prettier": "^3.8.2",
+    "storybook": "^10.3.5",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.1.4"
+  }
+}

package/prettier.config.ts

@@ -0,0 +1,30 @@
+import type { Config } from 'prettier';
+
+const config: Config = {
+  endOfLine: 'lf',
+  arrowParens: 'always',
+  semi: true,
+  trailingComma: 'all',
+  singleQuote: true,
+  printWidth: 80,
+  tabWidth: 2,
+  useTabs: false,
+  plugins: ['@trivago/prettier-plugin-sort-imports'],
+  importOrder: [
+    '^bun.*$',
+    '<THIRD_PARTY_MODULES>',
+    '^@/(.*)$',
+    '^[../]',
+    '^[./]',
+    '(.css|.scss)$',
+  ],
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true,
+  importOrderParserPlugins: [
+    'typescript',
+    'decorators-legacy',
+    'importAssertions',
+  ],
+};
+
+export default config;

package/src/elements/RouteElement.ts

@@ -0,0 +1,67 @@
+import type {
+  RouteComponent,
+  RouteContext,
+  RouteDefinition,
+} from '../models/index.ts';
+
+export interface RouteElementEnv {
+  document?: Document;
+}
+
+export class RouteElement extends HTMLElement {
+  public static readonly tag = 'wavelength-route';
+
+  public get path(): string {
+    return this.getAttribute('path') ?? '*';
+  }
+
+  public get componentTag(): string {
+    return this.getAttribute('component') ?? '';
+  }
+
+  public toDefinition(env: RouteElementEnv = {}): RouteDefinition | null {
+    const tag: string = this.componentTag;
+    const doc: Document | undefined = env.document;
+
+    if (!tag) {
+      console.warn(
+          `[route] Missing 'component' attribute on path="${this.path}"`,
+      );
+      return null;
+    }
+
+    if (!doc) {
+      return {
+        path: this.path,
+        routeComponent: {
+          mount() {},
+          unmount() {},
+        },
+      };
+    }
+
+    const routeComponent: RouteComponent = {
+      mount: (container: HTMLElement, routeContext: RouteContext) => {
+        const element = doc.createElement(tag) as HTMLElement & {
+          routeContext?: RouteContext;
+        };
+
+        element.routeContext = routeContext;
+
+        container.appendChild(element);
+      },
+      unmount: () => {
+        // optional: future cleanup hook
+      },
+    };
+
+    return {
+      path: this.path,
+      routeComponent,
+    };
+  }
+}
+
+if (!customElements.get(RouteElement.tag)) {
+  customElements.define(RouteElement.tag, RouteElement);
+}

package/src/elements/RouterElement.ts

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