@bquery/bquery 1.2.0 → 1.4.0

package/src/router/links.ts

@@ -0,0 +1,130 @@
+/**
+ * Link helpers for client-side navigation.
+ * @module bquery/router
+ */
+
+import { getActiveRouter } from './state';
+import { navigate } from './navigation';
+
+// ============================================================================
+// Router Link Helper
+// ============================================================================
+
+/**
+ * Creates click handler for router links.
+ * Attach to anchor elements to enable client-side navigation.
+ *
+ * @param path - Target path
+ * @param options - Navigation options
+ * @returns Click event handler
+ *
+ * @example
+ * ```ts
+ * import { link } from 'bquery/router';
+ * import { $ } from 'bquery/core';
+ *
+ * $('#nav-home').on('click', link('/'));
+ * $('#nav-about').on('click', link('/about'));
+ * ```
+ */
+export const link = (path: string, options: { replace?: boolean } = {}): ((e: Event) => void) => {
+  return (e: Event) => {
+    e.preventDefault();
+    void navigate(path, options).catch((err) => {
+      console.error('Navigation failed:', err);
+    });
+  };
+};
+
+/**
+ * Intercepts all link clicks within a container for client-side routing.
+ * Only intercepts links with matching origins and no target attribute.
+ *
+ * @param container - The container element to intercept links in
+ * @returns Cleanup function to remove the listener
+ *
+ * @example
+ * ```ts
+ * import { interceptLinks } from 'bquery/router';
+ *
+ * // Intercept all links in the app
+ * const cleanup = interceptLinks(document.body);
+ *
+ * // Later, remove the interceptor
+ * cleanup();
+ * ```
+ */
+export const interceptLinks = (container?: Element): (() => void) => {
+  // Provide safe default in DOM environments only
+  const targetContainer = container ?? (typeof document !== 'undefined' ? document.body : null);
+  if (!targetContainer) {
+    // No container available (SSR or invalid input)
+    return () => undefined;
+  }
+
+  const handler = (e: Event) => {
+    // Only intercept standard left-clicks without modifier keys
+    if (!(e instanceof MouseEvent)) return;
+    if (e.defaultPrevented) return; // Already handled
+    if (e.button !== 0) return; // Not left-click (middle-click opens new tab, right-click shows context menu)
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return; // Modifier keys (Ctrl/Cmd-click = new tab)
+
+    // Guard against non-Element targets and non-DOM environments
+    if (typeof Element === 'undefined' || !(e.target instanceof Element)) return;
+    const target = e.target as HTMLElement;
+    const anchor = target.closest('a');
+
+    if (!anchor) return;
+
+    // Cross-realm compatible anchor check: use owner document's constructor if available
+    const anchorWindow = anchor.ownerDocument.defaultView;
+    const AnchorConstructor = anchorWindow?.HTMLAnchorElement ?? HTMLAnchorElement;
+    if (!(anchor instanceof AnchorConstructor)) return;
+
+    if (anchor.target) return; // Has target attribute
+    if (anchor.hasAttribute('download')) return;
+    if (typeof window === 'undefined') return; // Non-window environment
+    if (anchor.origin !== window.location.origin) return; // External link
+
+    // Get active router config to handle base paths correctly.
+    // If no router is active, proceed with no base/hash; navigate() will throw a
+    // "No router initialized" error, which is caught and logged below.
+    const router = getActiveRouter();
+    if (!router) {
+      // No active router - trigger navigate(), allowing its error to be logged here
+      e.preventDefault();
+      void navigate(anchor.pathname + anchor.search + anchor.hash).catch((err) => {
+        console.error('Navigation failed:', err);
+      });
+      return;
+    }
+
+    const base = router.base;
+    const useHash = router.hash;
+
+    // Detect hash-routing mode: links written as href="#/page"
+    // In this case, anchor.hash contains the route path
+    let path: string;
+    if (useHash && anchor.hash && anchor.hash.startsWith('#/')) {
+      // Hash-routing mode: extract path from the hash
+      // e.g., href="#/page?foo=bar" → path = "/page?foo=bar"
+      path = anchor.hash.slice(1); // Remove leading #
+    } else {
+      // History mode: use pathname + search + hash
+      // Strip base from pathname to avoid duplication (router.push() re-adds it)
+      let pathname = anchor.pathname;
+      if (base && base !== '/' && pathname.startsWith(base)) {
+        pathname = pathname.slice(base.length) || '/';
+      }
+      path = pathname + anchor.search + anchor.hash;
+    }
+
+    e.preventDefault();
+    void navigate(path).catch((err) => {
+      console.error('Navigation failed:', err);
+    });
+  };
+
+  targetContainer.addEventListener('click', handler);
+  return () => targetContainer.removeEventListener('click', handler);
+};

package/src/router/match.ts

@@ -0,0 +1,106 @@
+/**
+ * Route matching helpers.
+ * @module bquery/router
+ */
+
+import { parseQuery } from './query';
+import type { Route, RouteDefinition } from './types';
+
+// ============================================================================
+// Route Matching
+// ============================================================================
+
+/**
+ * Converts a route path pattern to a RegExp for matching.
+ * Uses placeholder approach to preserve :param and * patterns during escaping.
+ * Returns positional capture groups for maximum compatibility.
+ * @internal
+ */
+const pathToRegex = (path: string): RegExp => {
+  // Handle wildcard-only route
+  if (path === '*') {
+    return /^.*$/;
+  }
+
+  // Unique placeholders using null chars (won't appear in normal paths)
+  const PARAM_MARKER = '\u0000P\u0000';
+  const WILDCARD_MARKER = '\u0000W\u0000';
+
+  // Step 1: Extract :param patterns before escaping
+  let pattern = path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, () => {
+    return PARAM_MARKER;
+  });
+
+  // Step 2: Extract * wildcards before escaping
+  pattern = pattern.replace(/\*/g, WILDCARD_MARKER);
+
+  // Step 3: Escape ALL regex metacharacters: \ ^ $ . * + ? ( ) [ ] { } |
+  pattern = pattern.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+
+  // Step 4: Restore param capture groups (positional, not named)
+  pattern = pattern.replace(/\u0000P\u0000/g, () => `([^/]+)`);
+
+  // Step 5: Restore wildcards as .*
+  pattern = pattern.replace(/\u0000W\u0000/g, '.*');
+
+  return new RegExp(`^${pattern}$`);
+};
+
+/**
+ * Extracts param names from a route path.
+ * @internal
+ */
+const extractParamNames = (path: string): string[] => {
+  const matches = path.match(/:([a-zA-Z_][a-zA-Z0-9_]*)/g);
+  return matches ? matches.map((m) => m.slice(1)) : [];
+};
+
+/**
+ * Matches a path against route definitions and extracts params.
+ * Uses positional captures for maximum compatibility.
+ * @internal
+ */
+export const matchRoute = (
+  path: string,
+  routes: RouteDefinition[]
+): { matched: RouteDefinition; params: Record<string, string> } | null => {
+  for (const route of routes) {
+    const regex = pathToRegex(route.path);
+    const match = path.match(regex);
+
+    if (match) {
+      const paramNames = extractParamNames(route.path);
+      const params: Record<string, string> = {};
+
+      // Map positional captures to param names
+      paramNames.forEach((name, index) => {
+        params[name] = match[index + 1] || '';
+      });
+
+      return { matched: route, params };
+    }
+  }
+
+  return null;
+};
+
+/**
+ * Creates a Route object from the current URL.
+ * @internal
+ */
+export const createRoute = (
+  pathname: string,
+  search: string,
+  hash: string,
+  routes: RouteDefinition[]
+): Route => {
+  const result = matchRoute(pathname, routes);
+
+  return {
+    path: pathname,
+    params: result?.params ?? {},
+    query: parseQuery(search),
+    matched: result?.matched ?? null,
+    hash: hash.replace(/^#/, ''),
+  };
+};

package/src/router/navigation.ts

@@ -0,0 +1,71 @@
+/**
+ * Navigation helpers and global router access.
+ * @module bquery/router
+ */
+
+import { getActiveRouter } from './state';
+
+/**
+ * Navigates to a new path.
+ *
+ * @param path - The path to navigate to
+ * @param options - Navigation options
+ *
+ * @example
+ * ```ts
+ * import { navigate } from 'bquery/router';
+ *
+ * // Push to history
+ * await navigate('/dashboard');
+ *
+ * // Replace current entry
+ * await navigate('/login', { replace: true });
+ * ```
+ */
+export const navigate = async (
+  path: string,
+  options: { replace?: boolean } = {}
+): Promise<void> => {
+  const activeRouter = getActiveRouter();
+  if (!activeRouter) {
+    throw new Error('bQuery router: No router initialized. Call createRouter() first.');
+  }
+
+  await activeRouter[options.replace ? 'replace' : 'push'](path);
+};
+
+/**
+ * Programmatically go back in history.
+ *
+ * @example
+ * ```ts
+ * import { back } from 'bquery/router';
+ * back();
+ * ```
+ */
+export const back = (): void => {
+  const activeRouter = getActiveRouter();
+  if (activeRouter) {
+    activeRouter.back();
+  } else {
+    history.back();
+  }
+};
+
+/**
+ * Programmatically go forward in history.
+ *
+ * @example
+ * ```ts
+ * import { forward } from 'bquery/router';
+ * forward();
+ * ```
+ */
+export const forward = (): void => {
+  const activeRouter = getActiveRouter();
+  if (activeRouter) {
+    activeRouter.forward();
+  } else {
+    history.forward();
+  }
+};

package/src/router/query.ts

@@ -0,0 +1,35 @@
+/**
+ * Query string helpers.
+ * @module bquery/router
+ */
+
+/**
+ * Parses query string into an object.
+ * Single values are stored as strings, duplicate keys become arrays.
+ * @internal
+ *
+ * @example
+ * parseQuery('?foo=1') // { foo: '1' }
+ * parseQuery('?tag=a&tag=b') // { tag: ['a', 'b'] }
+ * parseQuery('?x=1&y=2&x=3') // { x: ['1', '3'], y: '2' }
+ */
+export const parseQuery = (search: string): Record<string, string | string[]> => {
+  const query: Record<string, string | string[]> = {};
+  const params = new URLSearchParams(search);
+
+  params.forEach((value, key) => {
+    const existing = query[key];
+    if (existing === undefined) {
+      // First occurrence: store as string
+      query[key] = value;
+    } else if (Array.isArray(existing)) {
+      // Already an array: append
+      existing.push(value);
+    } else {
+      // Second occurrence: convert to array
+      query[key] = [existing, value];
+    }
+  });
+
+  return query;
+};

package/src/router/router.ts

@@ -0,0 +1,211 @@
+/**
+ * Router creation and lifecycle management.
+ * @module bquery/router
+ */
+
+import { createRoute } from './match';
+import { currentRoute, getActiveRouter, routeSignal, setActiveRouter } from './state';
+import type { NavigationGuard, Route, Router, RouterOptions } from './types';
+import { flattenRoutes } from './utils';
+
+// ============================================================================
+// Router Creation
+// ============================================================================
+
+/**
+ * Creates and initializes a router instance.
+ *
+ * @param options - Router configuration
+ * @returns The router instance
+ *
+ * @example
+ * ```ts
+ * import { createRouter } from 'bquery/router';
+ *
+ * const router = createRouter({
+ *   routes: [
+ *     { path: '/', component: () => import('./pages/Home') },
+ *     { path: '/about', component: () => import('./pages/About') },
+ *     { path: '/user/:id', component: () => import('./pages/User') },
+ *     { path: '*', component: () => import('./pages/NotFound') },
+ *   ],
+ *   base: '/app',
+ * });
+ *
+ * router.beforeEach((to, from) => {
+ *   if (to.path === '/admin' && !isAuthenticated()) {
+ *     return false; // Cancel navigation
+ *   }
+ * });
+ * ```
+ */
+export const createRouter = (options: RouterOptions): Router => {
+  // Clean up any existing router to prevent guard leakage
+  const existingRouter = getActiveRouter();
+  if (existingRouter) {
+    existingRouter.destroy();
+  }
+
+  const { routes, base = '', hash: useHash = false } = options;
+
+  // Instance-specific guards and hooks (not shared globally)
+  const beforeGuards: NavigationGuard[] = [];
+  const afterHooks: Array<(to: Route, from: Route) => void> = [];
+
+  // Flatten nested routes (base-relative, not including the base path)
+  const flatRoutes = flattenRoutes(routes);
+
+  /**
+   * Gets the current path from the URL.
+   */
+  const getCurrentPath = (): { pathname: string; search: string; hash: string } => {
+    if (useHash) {
+      const hashPath = window.location.hash.slice(1) || '/';
+      // In hash routing, URL structure is #/path?query#fragment
+      // Extract hash fragment first (after the second #)
+      const [pathWithQuery, hashPart = ''] = hashPath.split('#');
+      // Then extract query from the path
+      const [pathname, search = ''] = pathWithQuery.split('?');
+      return {
+        pathname,
+        search: search ? `?${search}` : '',
+        hash: hashPart ? `#${hashPart}` : '',
+      };
+    }
+
+    let pathname = window.location.pathname;
+    if (base && (pathname === base || pathname.startsWith(base + '/'))) {
+      pathname = pathname.slice(base.length) || '/';
+    }
+
+    return {
+      pathname,
+      search: window.location.search,
+      hash: window.location.hash,
+    };
+  };
+
+  /**
+   * Updates the route signal with current URL state.
+   */
+  const syncRoute = (): void => {
+    const { pathname, search, hash } = getCurrentPath();
+    const newRoute = createRoute(pathname, search, hash, flatRoutes);
+    routeSignal.value = newRoute;
+  };
+
+  /**
+   * Performs navigation with guards.
+   */
+  const performNavigation = async (
+    path: string,
+    method: 'pushState' | 'replaceState'
+  ): Promise<void> => {
+    const { pathname, search, hash } = getCurrentPath();
+    const from = createRoute(pathname, search, hash, flatRoutes);
+
+    // Parse the target path
+    const url = new URL(path, window.location.origin);
+    const to = createRoute(url.pathname, url.search, url.hash, flatRoutes);
+
+    // Run beforeEach guards
+    for (const guard of beforeGuards) {
+      const result = await guard(to, from);
+      if (result === false) {
+        return; // Cancel navigation
+      }
+    }
+
+    // Update browser history
+    const fullPath = useHash ? `#${path}` : `${base}${path}`;
+    history[method]({}, '', fullPath);
+
+    // Update route signal
+    syncRoute();
+
+    // Run afterEach hooks
+    for (const hook of afterHooks) {
+      hook(routeSignal.value, from);
+    }
+  };
+
+  /**
+   * Handle popstate events (back/forward).
+   */
+  const handlePopState = async (): Promise<void> => {
+    const { pathname, search, hash } = getCurrentPath();
+    const from = routeSignal.value;
+    const to = createRoute(pathname, search, hash, flatRoutes);
+
+    // Run beforeEach guards (supports async guards)
+    for (const guard of beforeGuards) {
+      const result = await guard(to, from);
+      if (result === false) {
+        // Restore previous state with full URL (including query/hash)
+        const queryString = new URLSearchParams(
+          Object.entries(from.query).flatMap(([key, value]) =>
+            Array.isArray(value) ? value.map((v) => [key, v]) : [[key, value]]
+          )
+        ).toString();
+        const search = queryString ? `?${queryString}` : '';
+        const hash = from.hash ? `#${from.hash}` : '';
+        const restorePath = useHash
+          ? `#${from.path}${search}${hash}`
+          : `${base}${from.path}${search}${hash}`;
+        history.replaceState({}, '', restorePath);
+        return;
+      }
+    }
+
+    syncRoute();
+
+    for (const hook of afterHooks) {
+      hook(routeSignal.value, from);
+    }
+  };
+
+  // Attach popstate listener
+  window.addEventListener('popstate', handlePopState);
+
+  // Initialize route
+  syncRoute();
+
+  const router: Router = {
+    push: (path: string) => performNavigation(path, 'pushState'),
+    replace: (path: string) => performNavigation(path, 'replaceState'),
+    back: () => history.back(),
+    forward: () => history.forward(),
+    go: (delta: number) => history.go(delta),
+
+    beforeEach: (guard: NavigationGuard) => {
+      beforeGuards.push(guard);
+      return () => {
+        const index = beforeGuards.indexOf(guard);
+        if (index > -1) beforeGuards.splice(index, 1);
+      };
+    },
+
+    afterEach: (hook: (to: Route, from: Route) => void) => {
+      afterHooks.push(hook);
+      return () => {
+        const index = afterHooks.indexOf(hook);
+        if (index > -1) afterHooks.splice(index, 1);
+      };
+    },
+
+    currentRoute,
+    routes: flatRoutes,
+    base,
+    hash: useHash,
+
+    destroy: () => {
+      window.removeEventListener('popstate', handlePopState);
+      beforeGuards.length = 0;
+      afterHooks.length = 0;
+      setActiveRouter(null);
+    },
+  };
+
+  setActiveRouter(router);
+  return router;
+};

package/src/router/state.ts

@@ -0,0 +1,46 @@
+/**
+ * Internal router state (active router and current route signal).
+ * @module bquery/router
+ */
+
+import { computed, signal, type ReadonlySignal, type Signal } from '../reactive/index';
+import type { Route, Router } from './types';
+
+// ============================================================================
+// Internal State
+// ============================================================================
+
+/** @internal */
+let activeRouter: Router | null = null;
+
+/** @internal */
+export const routeSignal: Signal<Route> = signal<Route>({
+  path: '',
+  params: {},
+  query: {},
+  matched: null,
+  hash: '',
+});
+
+/**
+ * Reactive signal containing the current route.
+ *
+ * @example
+ * ```ts
+ * import { currentRoute } from 'bquery/router';
+ * import { effect } from 'bquery/reactive';
+ *
+ * effect(() => {
+ *   document.title = `Page: ${currentRoute.value.path}`;
+ * });
+ * ```
+ */
+export const currentRoute: ReadonlySignal<Route> = computed(() => routeSignal.value);
+
+/** @internal */
+export const getActiveRouter = (): Router | null => activeRouter;
+
+/** @internal */
+export const setActiveRouter = (router: Router | null): void => {
+  activeRouter = router;
+};

package/src/router/types.ts

@@ -0,0 +1,93 @@
+/**
+ * Router types and public contracts.
+ * @module bquery/router
+ */
+
+import type { ReadonlySignal } from '../reactive/index';
+
+/**
+ * Represents a parsed route with matched params.
+ */
+export type Route = {
+  /** The current path (e.g., '/user/42') */
+  path: string;
+  /** Extracted route params (e.g., { id: '42' }) */
+  params: Record<string, string>;
+  /**
+   * Query string params.
+   * Each key maps to a single string value by default.
+   * Only keys that appear multiple times in the query string become arrays.
+   * @example
+   * // ?foo=1 → { foo: '1' }
+   * // ?tag=a&tag=b → { tag: ['a', 'b'] }
+   * // ?x=1&y=2&x=3 → { x: ['1', '3'], y: '2' }
+   */
+  query: Record<string, string | string[]>;
+  /** The matched route definition */
+  matched: RouteDefinition | null;
+  /** Hash fragment without # */
+  hash: string;
+};
+
+/**
+ * Route definition for configuration.
+ */
+export type RouteDefinition = {
+  /** Path pattern (e.g., '/user/:id', '/posts/*') */
+  path: string;
+  /** Component loader (sync or async) */
+  component: () => unknown | Promise<unknown>;
+  /** Optional route name for programmatic navigation */
+  name?: string;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+  /** Nested child routes */
+  children?: RouteDefinition[];
+};
+
+/**
+ * Router configuration options.
+ */
+export type RouterOptions = {
+  /** Array of route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes (default: '') */
+  base?: string;
+  /** Use hash-based routing instead of history (default: false) */
+  hash?: boolean;
+};
+
+/**
+ * Navigation guard function type.
+ */
+export type NavigationGuard = (to: Route, from: Route) => boolean | void | Promise<boolean | void>;
+
+/**
+ * Router instance returned by createRouter.
+ */
+export type Router = {
+  /** Navigate to a path */
+  push: (path: string) => Promise<void>;
+  /** Replace current history entry */
+  replace: (path: string) => Promise<void>;
+  /** Go back in history */
+  back: () => void;
+  /** Go forward in history */
+  forward: () => void;
+  /** Go to a specific history entry */
+  go: (delta: number) => void;
+  /** Add a beforeEach guard */
+  beforeEach: (guard: NavigationGuard) => () => void;
+  /** Add an afterEach hook */
+  afterEach: (hook: (to: Route, from: Route) => void) => () => void;
+  /** Current route (reactive) */
+  currentRoute: ReadonlySignal<Route>;
+  /** All route definitions */
+  routes: RouteDefinition[];
+  /** Base path for all routes */
+  base: string;
+  /** Whether hash-based routing is enabled */
+  hash: boolean;
+  /** Destroy the router and cleanup listeners */
+  destroy: () => void;
+};