@bromscandium/router 1.0.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bromscandium/router",
+  "version": "1.0.0",
+  "description": "BromiumJS router with file-based routing support",
+  "author": "bromscandium",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bromscandium/bromiumjs.git",
+    "directory": "packages/router"
+  },
+  "homepage": "https://github.com/bromscandium/bromiumjs#readme",
+  "bugs": {
+    "url": "https://github.com/bromscandium/bromiumjs/issues"
+  },
+  "keywords": ["bromium", "bromiumjs", "router", "file-based-routing", "spa"],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@bromscandium/core": "^1.0.0",
+    "@bromscandium/runtime": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/components.tsx

@@ -0,0 +1,411 @@
+/**
+ * Router components: Link, RouterView, Redirect, and Navigate.
+ * @module
+ */
+
+import {ref} from '@bromscandium/core';
+import {jsx, VNode} from '@bromscandium/runtime';
+import {useRoute, useRouter} from './hooks.js';
+import {NavigationTarget} from './router.js';
+
+/**
+ * Props for the Link component.
+ */
+interface LinkProps {
+  /** The target path or navigation object */
+  to: string | NavigationTarget;
+  /** Child elements to render inside the link */
+  children?: any;
+  /** CSS class name */
+  className?: string;
+  /** Class name to add when route is active (includes nested) */
+  activeClassName?: string;
+  /** Class name to add when route exactly matches */
+  exactActiveClassName?: string;
+  /** If true, replace current history entry instead of pushing */
+  replace?: boolean;
+  /** HTML target attribute (e.g., "_blank") */
+  target?: string;
+  /** HTML rel attribute for external links */
+  rel?: string;
+  /** Additional click handler */
+  onClick?: (e: MouseEvent) => void;
+  /** Additional attributes passed to the anchor element */
+  [key: string]: any;
+}
+
+/**
+ * A navigation link component that integrates with the router.
+ * Handles click events to perform client-side navigation.
+ *
+ * @param props - Link component props
+ * @returns An anchor element VNode
+ *
+ * @example
+ * ```tsx
+ * <Link to="/about">About</Link>
+ *
+ * <Link to="/dashboard" activeClassName="active">Dashboard</Link>
+ *
+ * <Link to={{ path: '/user', query: { id: '123' } }}>User</Link>
+ * ```
+ */
+export function Link(props: LinkProps): VNode {
+  const router = useRouter();
+  const route = useRoute();
+
+  const {
+    to,
+    children,
+    className = '',
+    activeClassName = '',
+    exactActiveClassName = '',
+    replace = false,
+    target,
+    rel,
+    onClick,
+    ...rest
+  } = props;
+
+  const href = typeof to === 'string' ? to : (to.path || '/');
+
+  const currentPath = route.value.path;
+  const base = router.base || '';
+  const comparePath = base ? href.replace(new RegExp(`^${base}`), '') || '/' : href;
+
+  const isExactActive = currentPath === comparePath;
+  const isActive = isExactActive || currentPath.startsWith(comparePath + '/');
+
+  let finalClassName = className;
+  if (isActive && activeClassName) {
+    finalClassName = `${finalClassName} ${activeClassName}`.trim();
+  }
+  if (isExactActive && exactActiveClassName) {
+    finalClassName = `${finalClassName} ${exactActiveClassName}`.trim();
+  }
+
+  function handleClick(e: MouseEvent) {
+    onClick?.(e);
+
+    if (e.defaultPrevented) return;
+
+    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return;
+
+    if (target) return;
+
+    e.preventDefault();
+
+    if (replace) {
+      router.replace(to);
+    } else {
+      router.push(to);
+    }
+  }
+
+  return jsx('a', {
+    href,
+    className: finalClassName || undefined,
+    target,
+    rel,
+    onClick: handleClick,
+    children,
+    ...rest,
+  });
+}
+
+/**
+ * Props for the RouterView component.
+ */
+interface RouterViewProps {
+  /** The nesting depth for nested RouterViews (usually auto-detected) */
+  depth?: number;
+}
+
+let routerViewDepth = 0;
+
+const componentCache = new Map<string, any>();
+
+const layoutCache = new Map<string, any>();
+
+const pendingLoads = new Map<string, Promise<any>>();
+
+const renderVersion = ref(0);
+
+/**
+ * Renders the component for the current matched route.
+ * Handles lazy loading and layout wrapping automatically.
+ *
+ * @param props - RouterView component props
+ * @returns The rendered route component or null
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <div>
+ *       <nav>...</nav>
+ *       <RouterView />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function RouterView(props: RouterViewProps): VNode | null {
+  const { depth: explicitDepth } = props;
+  const route = useRoute();
+
+  void renderVersion.value;
+
+  const currentDepth = explicitDepth ?? routerViewDepth;
+  const matched = route.value.matched[currentDepth];
+
+  if (!matched) {
+    return null;
+  }
+
+  const routePath = matched.path;
+  const routeConfig = matched.route;
+
+  if (routeConfig.layout) {
+    const layoutKey = `layout:${routePath}`;
+    return loadAndRenderLayoutWithPage(
+      routeConfig.layout,
+      layoutKey,
+      routeConfig.component,
+      routePath,
+      route.value.fullPath,
+      currentDepth
+    );
+  }
+
+  return loadAndRenderComponent(
+    routeConfig.component,
+    routePath,
+    route.value.fullPath,
+    currentDepth
+  );
+}
+
+function loadAndRenderComponent(
+  componentModule: () => Promise<{ default: any }> | { default: any },
+  routePath: string,
+  fullPath: string,
+  currentDepth: number
+): VNode | null {
+  if (componentCache.has(routePath)) {
+    const Component = componentCache.get(routePath);
+    routerViewDepth = currentDepth + 1;
+    try {
+      return jsx(Component, {
+        key: fullPath,
+      });
+    } finally {
+      routerViewDepth = currentDepth;
+    }
+  }
+
+  if (typeof componentModule === 'function') {
+    if (!pendingLoads.has(routePath)) {
+      const loadPromise = componentModule();
+
+      if (loadPromise && typeof (loadPromise as any).then === 'function') {
+        pendingLoads.set(routePath, loadPromise as Promise<any>);
+
+        (loadPromise as Promise<any>).then((result) => {
+          const Component = result.default || result;
+          componentCache.set(routePath, Component);
+          pendingLoads.delete(routePath);
+          renderVersion.value++;
+        }).catch((error) => {
+          console.error('Failed to load route component:', error);
+          pendingLoads.delete(routePath);
+        });
+
+        return jsx('div', {
+          className: 'router-loading',
+          children: '',
+        });
+      } else {
+        const Component = (loadPromise as any).default || loadPromise;
+        componentCache.set(routePath, Component);
+
+        routerViewDepth = currentDepth + 1;
+        try {
+          return jsx(Component, {
+            key: fullPath,
+          });
+        } finally {
+          routerViewDepth = currentDepth;
+        }
+      }
+    } else {
+      return jsx('div', {
+        className: 'router-loading',
+        children: '',
+      });
+    }
+  } else {
+    const Component = (componentModule as any).default || componentModule;
+    componentCache.set(routePath, Component);
+
+    routerViewDepth = currentDepth + 1;
+    try {
+      return jsx(Component, {
+        key: fullPath,
+      });
+    } finally {
+      routerViewDepth = currentDepth;
+    }
+  }
+
+  return null;
+}
+
+function loadAndRenderLayoutWithPage(
+  layoutModule: () => Promise<{ default: any }> | { default: any },
+  layoutKey: string,
+  pageModule: () => Promise<{ default: any }> | { default: any },
+  routePath: string,
+  fullPath: string,
+  currentDepth: number
+): VNode | null {
+  const layoutLoaded = layoutCache.has(layoutKey);
+  const pageLoaded = componentCache.has(routePath);
+
+  if (layoutLoaded && pageLoaded) {
+    const Layout = layoutCache.get(layoutKey);
+    const PageComponent = componentCache.get(routePath);
+
+    routerViewDepth = currentDepth + 1;
+    try {
+      const pageElement = jsx(PageComponent, { key: fullPath });
+      return jsx(Layout, { children: pageElement });
+    } finally {
+      routerViewDepth = currentDepth;
+    }
+  }
+
+  if (!layoutLoaded && typeof layoutModule === 'function' && !pendingLoads.has(layoutKey)) {
+    const loadPromise = layoutModule();
+
+    if (loadPromise && typeof (loadPromise as any).then === 'function') {
+      pendingLoads.set(layoutKey, loadPromise as Promise<any>);
+
+      (loadPromise as Promise<any>).then((result) => {
+        const Layout = result.default || result;
+        layoutCache.set(layoutKey, Layout);
+        pendingLoads.delete(layoutKey);
+        renderVersion.value++;
+      }).catch((error) => {
+        console.error('Failed to load layout:', error);
+        pendingLoads.delete(layoutKey);
+      });
+    } else {
+      const Layout = (loadPromise as any).default || loadPromise;
+      layoutCache.set(layoutKey, Layout);
+    }
+  }
+
+  if (!pageLoaded && typeof pageModule === 'function' && !pendingLoads.has(routePath)) {
+    const loadPromise = pageModule();
+
+    if (loadPromise && typeof (loadPromise as any).then === 'function') {
+      pendingLoads.set(routePath, loadPromise as Promise<any>);
+
+      (loadPromise as Promise<any>).then((result) => {
+        const PageComponent = result.default || result;
+        componentCache.set(routePath, PageComponent);
+        pendingLoads.delete(routePath);
+        renderVersion.value++;
+      }).catch((error) => {
+        console.error('Failed to load page component:', error);
+        pendingLoads.delete(routePath);
+      });
+    } else {
+      const PageComponent = (loadPromise as any).default || loadPromise;
+      componentCache.set(routePath, PageComponent);
+    }
+  }
+
+  return jsx('div', {
+    className: 'router-loading',
+    children: '',
+  });
+}
+
+/**
+ * Props for the Redirect component.
+ */
+interface RedirectProps {
+  /** The target path or navigation object */
+  to: string | NavigationTarget;
+  /** If true, replace current history entry (default: true) */
+  replace?: boolean;
+}
+
+/**
+ * A component that performs a redirect when rendered.
+ * Useful for redirecting from one route to another.
+ *
+ * @param props - Redirect component props
+ * @returns null (performs navigation as side effect)
+ *
+ * @example
+ * ```tsx
+ * // In a route component
+ * if (!isAuthenticated) {
+ *   return <Redirect to="/login" />;
+ * }
+ * ```
+ */
+export function Redirect(props: RedirectProps): null {
+  const router = useRouter();
+  const { to, replace = true } = props;
+
+  if (replace) {
+    router.replace(to);
+  } else {
+    router.push(to);
+  }
+
+  return null;
+}
+
+/**
+ * Props for the Navigate component.
+ */
+interface NavigateProps {
+  /** The target path or navigation object */
+  to: string | NavigationTarget;
+  /** If true, replace current history entry instead of pushing */
+  replace?: boolean;
+}
+
+/**
+ * A component that performs navigation when rendered.
+ * Alternative to using the router imperatively.
+ *
+ * @param props - Navigate component props
+ * @returns null (performs navigation as side effect)
+ *
+ * @example
+ * ```tsx
+ * function AfterSubmit({ success }) {
+ *   if (success) {
+ *     return <Navigate to="/success" />;
+ *   }
+ *   return <div>Form</div>;
+ * }
+ * ```
+ */
+export function Navigate(props: NavigateProps): null {
+  const router = useRouter();
+
+  if (props.replace) {
+    router.replace(props.to);
+  } else {
+    router.push(props.to);
+  }
+
+  return null;
+}

package/src/hooks.ts

@@ -0,0 +1,180 @@
+/**
+ * Router hooks for components.
+ * @module
+ */
+
+import { computed, ComputedRef, Ref } from '@bromscandium/core';
+import { getRouter, Router, RouteLocation } from './router.js';
+
+/**
+ * Returns the router instance.
+ * Must be called within a component where a router has been created.
+ *
+ * @returns The router instance
+ * @throws Error if called outside of router context
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   const router = useRouter();
+ *
+ *   function handleClick() {
+ *     router.push('/dashboard');
+ *   }
+ *
+ *   return <button onClick={handleClick}>Go to Dashboard</button>;
+ * }
+ * ```
+ */
+export function useRouter(): Router {
+  const router = getRouter();
+  if (!router) {
+    throw new Error(
+      'useRouter() called outside of router context. ' +
+      'Make sure you have created a router with createRouter() and mounted it.'
+    );
+  }
+  return router;
+}
+
+/**
+ * Returns a reactive reference to the current route location.
+ *
+ * @returns A ref containing the current RouteLocation
+ *
+ * @example
+ * ```ts
+ * function Breadcrumb() {
+ *   const route = useRoute();
+ *
+ *   return <span>Current path: {route.value.path}</span>;
+ * }
+ * ```
+ */
+export function useRoute(): Ref<RouteLocation> {
+  const router = useRouter();
+  return router.currentRoute;
+}
+
+/**
+ * Returns a computed ref of the current route parameters.
+ *
+ * @returns A computed ref containing route params
+ *
+ * @example
+ * ```ts
+ * // For route /users/:id
+ * function UserProfile() {
+ *   const params = useParams();
+ *
+ *   return <div>User ID: {params.value.id}</div>;
+ * }
+ * ```
+ */
+export function useParams(): ComputedRef<Record<string, string>> {
+  const route = useRoute();
+  return computed(() => route.value.params);
+}
+
+/**
+ * Returns a computed ref of the current query string parameters.
+ *
+ * @returns A computed ref containing query params
+ *
+ * @example
+ * ```ts
+ * // For URL /search?q=hello
+ * function SearchResults() {
+ *   const query = useQuery();
+ *
+ *   return <div>Searching for: {query.value.q}</div>;
+ * }
+ * ```
+ */
+export function useQuery(): ComputedRef<Record<string, string>> {
+  const route = useRoute();
+  return computed(() => route.value.query);
+}
+
+/**
+ * Returns a computed ref of the merged metadata from all matched routes.
+ *
+ * @returns A computed ref containing route metadata
+ *
+ * @example
+ * ```ts
+ * function PageTitle() {
+ *   const meta = useRouteMeta();
+ *
+ *   return <title>{meta.value.title || 'My App'}</title>;
+ * }
+ * ```
+ */
+export function useRouteMeta(): ComputedRef<Record<string, any>> {
+  const route = useRoute();
+  return computed(() => route.value.meta);
+}
+
+/**
+ * Returns navigation helper functions from the router.
+ *
+ * @returns An object with push, replace, back, forward, and go methods
+ *
+ * @example
+ * ```ts
+ * function Navigation() {
+ *   const { push, back } = useNavigate();
+ *
+ *   return (
+ *     <>
+ *       <button onClick={back}>Back</button>
+ *       <button onClick={() => push('/home')}>Home</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useNavigate() {
+  const router = useRouter();
+
+  return {
+    push: router.push,
+    replace: router.replace,
+    back: router.back,
+    forward: router.forward,
+    go: router.go,
+  };
+}
+
+/**
+ * Returns a computed boolean indicating if the current route matches a path.
+ *
+ * @param path - A string path or RegExp to match against
+ * @returns A computed ref that is true when the route matches
+ *
+ * @example
+ * ```ts
+ * function NavLink({ to, children }) {
+ *   const isActive = useRouteMatch(to);
+ *
+ *   return (
+ *     <a href={to} className={isActive.value ? 'active' : ''}>
+ *       {children}
+ *     </a>
+ *   );
+ * }
+ * ```
+ */
+export function useRouteMatch(path: string | RegExp): ComputedRef<boolean> {
+  const route = useRoute();
+
+  return computed(() => {
+    const currentPath = route.value.path;
+
+    if (typeof path === 'string') {
+      return currentPath === path || currentPath.startsWith(path + '/');
+    }
+
+    return path.test(currentPath);
+  });
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Router package exports
+
+export {
+  createRouter,
+  getRouter,
+  setRouter,
+  type Router,
+  type Route,
+  type RouteLocation,
+  type MatchedRoute,
+  type NavigationTarget,
+  type NavigationGuard,
+  type NavigationHook,
+} from './router.js';
+
+export {
+  useRouter,
+  useRoute,
+  useParams,
+  useQuery,
+  useRouteMeta,
+  useNavigate,
+  useRouteMatch,
+} from './hooks.js';
+
+export {
+  Link,
+  RouterView,
+  Redirect,
+  Navigate,
+} from './components.js';