@bquery/bquery 1.6.0 → 1.7.0

package/src/router/bq-link.ts

@@ -0,0 +1,279 @@
+/**
+ * `<bq-link>` custom element for declarative SPA navigation.
+ *
+ * Exposes an accessible custom element that behaves like a link for
+ * client-side routing. Automatically toggles an active class when the
+ * target path matches the current route.
+ *
+ * @module bquery/router
+ *
+ * @example
+ * ```html
+ * <bq-link to="/">Home</bq-link>
+ * <bq-link to="/about" active-class="selected">About</bq-link>
+ * <bq-link to="/settings" replace exact>Settings</bq-link>
+ * ```
+ */
+
+import { effect, type CleanupFn } from '../reactive/index';
+import { navigate } from './navigation';
+import { getActiveRouter, routeSignal } from './state';
+
+/**
+ * Default CSS class applied when the link's target path is active.
+ * @internal
+ */
+const DEFAULT_ACTIVE_CLASS = 'active';
+
+/** @internal */
+const tokenizeClassNames = (value: string): string[] => {
+  return value
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 0);
+};
+
+/** @internal SSR-safe base class for environments without HTMLElement. */
+const BQ_LINK_BASE =
+  typeof HTMLElement !== 'undefined' ? HTMLElement : (class {} as unknown as typeof HTMLElement);
+
+/**
+ * `<bq-link>` — A navigation custom element for bQuery routers.
+ *
+ * Attributes:
+ * - `to` — Target path (required). Example: `to="/dashboard"`.
+ * - `replace` — If present, replaces the current history entry instead of pushing.
+ * - `exact` — If present, the active class is only applied on an exact path match.
+ * - `active-class` — CSS class added when the route is active (default: `'active'`).
+ *
+ * The custom element itself acts as the interactive link target using
+ * `role="link"` and keyboard handling. It does not render a native `<a>`,
+ * so browser-native link affordances like context-menu "open in new tab"
+ * are not provided automatically.
+ *
+ * @example
+ * ```ts
+ * import { registerBqLink } from '@bquery/bquery/router';
+ *
+ * // Register the <bq-link> element (idempotent)
+ * registerBqLink();
+ *
+ * // Then use in HTML:
+ * // <bq-link to="/about">About</bq-link>
+ * ```
+ */
+export class BqLinkElement extends BQ_LINK_BASE {
+  /** @internal */
+  private _cleanup: CleanupFn | null = null;
+
+  /** @internal */
+  private _trackedActiveClasses = new Map<string, boolean>();
+
+  static get observedAttributes(): string[] {
+    return ['to', 'replace', 'exact', 'active-class'];
+  }
+
+  /** The target path for navigation. */
+  get to(): string {
+    const to = this.getAttribute('to');
+    return to == null || to.trim() === '' ? '/' : to;
+  }
+
+  set to(value: string) {
+    this.setAttribute('to', value);
+  }
+
+  /** Whether to replace the current history entry. */
+  get replace(): boolean {
+    return this.hasAttribute('replace');
+  }
+
+  set replace(value: boolean) {
+    if (value) {
+      this.setAttribute('replace', '');
+    } else {
+      this.removeAttribute('replace');
+    }
+  }
+
+  /** Whether to match the path exactly for active class. */
+  get exact(): boolean {
+    return this.hasAttribute('exact');
+  }
+
+  set exact(value: boolean) {
+    if (value) {
+      this.setAttribute('exact', '');
+    } else {
+      this.removeAttribute('exact');
+    }
+  }
+
+  /** CSS class applied when the route is active. */
+  get activeClass(): string {
+    return this.getAttribute('active-class') ?? DEFAULT_ACTIVE_CLASS;
+  }
+
+  set activeClass(value: string) {
+    this.setAttribute('active-class', value);
+  }
+
+  /** @internal */
+  connectedCallback(): void {
+    // Set role for accessibility if not an <a> already
+    if (!this.getAttribute('role')) {
+      this.setAttribute('role', 'link');
+    }
+
+    // Make focusable if not already
+    if (!this.hasAttribute('tabindex')) {
+      this.setAttribute('tabindex', '0');
+    }
+
+    // Attach click handler
+    this.addEventListener('click', this._handleClick);
+    this.addEventListener('keydown', this._handleKeydown);
+
+    // Set up reactive active-class tracking
+    this._setupActiveTracking();
+  }
+
+  /** @internal */
+  disconnectedCallback(): void {
+    this.removeEventListener('click', this._handleClick);
+    this.removeEventListener('keydown', this._handleKeydown);
+
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = null;
+    }
+
+    this._clearTrackedActiveClasses();
+  }
+
+  /** @internal */
+  attributeChangedCallback(name: string, _oldValue: string | null, _newValue: string | null): void {
+    // Re-setup active tracking when relevant attributes change
+    if (name === 'to' || name === 'exact' || name === 'active-class') {
+      if (this.isConnected) {
+        this._setupActiveTracking();
+      }
+    }
+  }
+
+  /**
+   * Sets up the reactive effect that toggles the active CSS class
+   * based on the current route.
+   * @internal
+   */
+  private _setupActiveTracking(): void {
+    // Clean up previous effect
+    if (this._cleanup) {
+      this._cleanup();
+      this._cleanup = null;
+    }
+
+    this._clearTrackedActiveClasses();
+
+    const targetPath = this.to;
+    const exactMatch = this.exact;
+    const cssClasses = tokenizeClassNames(this.activeClass);
+    this._trackedActiveClasses = new Map(
+      cssClasses.map((cssClass) => [cssClass, this.classList.contains(cssClass)])
+    );
+
+    this._cleanup = effect(() => {
+      const current = routeSignal.value.path;
+      const isMatch = exactMatch
+        ? current === targetPath
+        : targetPath === '/'
+          ? current === '/'
+          : current === targetPath ||
+            current.startsWith(targetPath.endsWith('/') ? targetPath : targetPath + '/');
+
+      for (const cssClass of cssClasses) {
+        const wasPresentInitially = this._trackedActiveClasses.get(cssClass) ?? false;
+        this.classList.toggle(cssClass, isMatch || wasPresentInitially);
+      }
+
+      // Update aria-current for accessibility
+      if (isMatch) {
+        this.setAttribute('aria-current', 'page');
+      } else {
+        this.removeAttribute('aria-current');
+      }
+    });
+  }
+
+  /** @internal */
+  private _clearTrackedActiveClasses(): void {
+    for (const [cssClass, wasPresentInitially] of this._trackedActiveClasses) {
+      this.classList.toggle(cssClass, wasPresentInitially);
+    }
+    this._trackedActiveClasses.clear();
+  }
+
+  /**
+   * Handles click events for SPA navigation.
+   * @internal
+   */
+  private _handleClick = (e: Event): void => {
+    if (!(e instanceof MouseEvent)) return;
+    if (e.defaultPrevented) return;
+    if (e.button !== 0) return; // Only left clicks
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
+
+    e.preventDefault();
+    this._navigate();
+  };
+
+  /**
+   * Handles keyboard activation (Enter).
+   * @internal
+   */
+  private _handleKeydown = (e: Event): void => {
+    if (e instanceof KeyboardEvent && e.key === 'Enter') {
+      e.preventDefault();
+      this._navigate();
+    }
+  };
+
+  /**
+   * Performs the actual navigation.
+   * @internal
+   */
+  private _navigate(): void {
+    const targetPath = this.to;
+    if (!targetPath) return;
+    if (!getActiveRouter()) return;
+
+    void navigate(targetPath, { replace: this.replace }).catch((err) => {
+      console.error('bq-link: Navigation failed:', err);
+    });
+  }
+}
+
+/**
+ * Registers the `<bq-link>` custom element.
+ *
+ * This function is idempotent — calling it multiple times is safe.
+ * The element is registered under the tag name `bq-link`.
+ *
+ * @example
+ * ```ts
+ * import { registerBqLink } from '@bquery/bquery/router';
+ *
+ * registerBqLink();
+ *
+ * // Now use <bq-link to="/about">About</bq-link> in HTML
+ * ```
+ */
+export const registerBqLink = (): void => {
+  if (
+    typeof HTMLElement !== 'undefined' &&
+    typeof customElements !== 'undefined' &&
+    !customElements.get('bq-link')
+  ) {
+    customElements.define('bq-link', BqLinkElement);
+  }
+};

package/src/router/constraints.ts

@@ -0,0 +1,201 @@
+/**
+ * Shared helpers for validating and normalizing route param constraints.
+ * @internal
+ */
+
+const MAX_ROUTE_CONSTRAINT_CACHE_SIZE = 128;
+const normalizedConstraintCache = new Map<string, string>();
+const compiledConstraintRegexCache = new Map<string, RegExp>();
+
+const setBoundedCacheEntry = <T>(cache: Map<string, T>, key: string, value: T): void => {
+  if (cache.has(key)) {
+    cache.delete(key);
+  }
+
+  cache.set(key, value);
+
+  if (cache.size <= MAX_ROUTE_CONSTRAINT_CACHE_SIZE) {
+    return;
+  }
+
+  const oldestKey = cache.keys().next().value;
+  if (oldestKey !== undefined) {
+    cache.delete(oldestKey);
+  }
+};
+
+/**
+ * Detects potentially super-linear (ReDoS) patterns caused by quantified
+ * groups that already contain inner quantifiers, such as `(a+)+` or `(a*)*`.
+ * @internal
+ */
+const hasNestedQuantifier = (pattern: string): boolean => {
+  const groupQuantifierStack: boolean[] = [];
+  let inCharClass = false;
+
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+
+    if (ch === '\\' && i + 1 < pattern.length) {
+      i++;
+      continue;
+    }
+
+    if (ch === '[' && !inCharClass) {
+      inCharClass = true;
+      continue;
+    }
+    if (ch === ']' && inCharClass) {
+      inCharClass = false;
+      continue;
+    }
+    if (inCharClass) continue;
+
+    if (ch === '(') {
+      groupQuantifierStack.push(false);
+      continue;
+    }
+
+    if (ch === ')') {
+      const groupHasInnerQuantifier = groupQuantifierStack.pop() ?? false;
+      // Check if the closing paren is followed by a quantifier
+      const next = pattern[i + 1];
+      if (groupHasInnerQuantifier && (next === '+' || next === '*' || next === '?' || next === '{')) {
+        return true;
+      }
+      if (groupHasInnerQuantifier && groupQuantifierStack.length > 0) {
+        groupQuantifierStack[groupQuantifierStack.length - 1] = true;
+      }
+      continue;
+    }
+
+    if (groupQuantifierStack.length > 0) {
+      if (ch === '?' && i > 0 && pattern[i - 1] === '(') {
+        continue;
+      }
+
+      if (ch === '+' || ch === '*' || ch === '?' || ch === '{') {
+        groupQuantifierStack[groupQuantifierStack.length - 1] = true;
+      }
+    }
+  }
+
+  return false;
+};
+
+const normalizeConstraintCaptures = (constraint: string): string => {
+  let normalized = '';
+  let inCharacterClass = false;
+
+  for (let i = 0; i < constraint.length; i++) {
+    const char = constraint[i];
+
+    if (char === '\\' && i + 1 < constraint.length) {
+      if (!inCharacterClass && constraint[i + 1] >= '1' && constraint[i + 1] <= '9') {
+        throw new Error(
+          `bQuery router: Route constraints cannot use backreferences: "${constraint}".`
+        );
+      }
+
+      if (!inCharacterClass && constraint[i + 1] === 'k' && constraint[i + 2] === '<') {
+        throw new Error(
+          `bQuery router: Route constraints cannot use backreferences: "${constraint}".`
+        );
+      }
+
+      normalized += char + constraint[i + 1];
+      i++;
+      continue;
+    }
+
+    if (char === '[' && !inCharacterClass) {
+      inCharacterClass = true;
+      normalized += char;
+      continue;
+    }
+
+    if (char === ']' && inCharacterClass) {
+      inCharacterClass = false;
+      normalized += char;
+      continue;
+    }
+
+    if (!inCharacterClass && char === '(') {
+      if (i + 1 < constraint.length && constraint[i + 1] === '?') {
+        if (constraint[i + 2] === '<') {
+          if (constraint[i + 3] === '=' || constraint[i + 3] === '!') {
+            normalized += '(';
+            continue;
+          }
+
+          const namedCaptureEnd = constraint.indexOf('>', i + 3);
+          if (namedCaptureEnd === -1) {
+            throw new Error(
+              `bQuery router: Invalid route constraint named capture group: "${constraint}".`
+            );
+          }
+          normalized += '(?:';
+          i = namedCaptureEnd;
+          continue;
+        }
+
+        normalized += '(';
+        continue;
+      }
+
+      normalized += '(?:';
+      continue;
+    }
+
+    normalized += char;
+  }
+
+  return normalized;
+};
+
+export const getNormalizedRouteConstraint = (constraint: string): string => {
+  const cached = normalizedConstraintCache.get(constraint);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const normalized = normalizeConstraintCaptures(constraint);
+  setBoundedCacheEntry(normalizedConstraintCache, constraint, normalized);
+  return normalized;
+};
+
+export const getRouteConstraintRegex = (constraint: string): RegExp => {
+  const normalizedConstraint = getNormalizedRouteConstraint(constraint);
+  const cached = compiledConstraintRegexCache.get(normalizedConstraint);
+  if (cached) {
+    return cached;
+  }
+
+  if (hasNestedQuantifier(normalizedConstraint)) {
+    throw new Error(
+      `bQuery router: Route constraint contains a potentially catastrophic (ReDoS) pattern. Nested quantifiers are not allowed: "${constraint}".`
+    );
+  }
+
+  try {
+    const compiled = new RegExp(`^(?:${normalizedConstraint})$`);
+    setBoundedCacheEntry(compiledConstraintRegexCache, normalizedConstraint, compiled);
+    return compiled;
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(
+        `bQuery router: Invalid route constraint regex "${constraint}": ${error.message}`
+      );
+    }
+    throw error;
+  }
+};
+
+export const routeConstraintMatches = (constraint: string, value: string): boolean => {
+  return getRouteConstraintRegex(constraint).test(value);
+};
+
+export const clearRouteConstraintCache = (): void => {
+  normalizedConstraintCache.clear();
+  compiledConstraintRegexCache.clear();
+};

package/src/router/index.ts

@@ -1,41 +1,49 @@
-/**
- * Minimal SPA router with History API integration.
- *
- * This module provides a lightweight, signal-based router for single-page
- * applications. Features include:
- * - History API navigation
- * - Route matching with params and wildcards
- * - Lazy route loading
- * - Navigation guards (beforeEach, afterEach)
- * - Reactive current route via signals
- * - Multi-value query params (e.g., `?tag=a&tag=b` → `{ tag: ['a', 'b'] }`)
- *
- * @module bquery/router
- *
- * @example
- * ```ts
- * import { createRouter, navigate, currentRoute } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
- *
- * const router = createRouter({
- *   routes: [
- *     { path: '/', component: () => import('./Home') },
- *     { path: '/user/:id', component: () => import('./User') },
- *     { path: '*', component: () => import('./NotFound') },
- *   ],
- * });
- *
- * effect(() => {
- *   console.log('Route changed:', currentRoute.value);
- * });
- *
- * navigate('/user/42');
- * ```
- */
-
-export { interceptLinks, link } from './links';
-export { back, forward, navigate } from './navigation';
-export { createRouter } from './router';
-export { currentRoute } from './state';
-export type { NavigationGuard, Route, RouteDefinition, Router, RouterOptions } from './types';
-export { isActive, isActiveSignal, resolve } from './utils';
+/**
+ * Minimal SPA router with History API integration.
+ *
+ * This module provides a lightweight, signal-based router for single-page
+ * applications. Features include:
+ * - History API navigation
+ * - Route matching with params, wildcards, and regex constraints
+ * - Lazy route loading
+ * - Navigation guards (beforeEach, afterEach, per-route beforeEnter)
+ * - Reactive current route via signals
+ * - `useRoute()` composable for fine-grained reactive access
+ * - Route redirects via `redirectTo`
+ * - Scroll position restoration on back/forward
+ * - Multi-value query params (e.g., `?tag=a&tag=b` → `{ tag: ['a', 'b'] }`)
+ *
+ * @module bquery/router
+ *
+ * @example
+ * ```ts
+ * import { createRouter, navigate, currentRoute, useRoute } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const router = createRouter({
+ *   routes: [
+ *     { path: '/', component: () => import('./Home') },
+ *     { path: '/user/:id(\\d+)', component: () => import('./User') },
+ *     { path: '/old', redirectTo: '/new' },
+ *     { path: '*', component: () => import('./NotFound') },
+ *   ],
+ *   scrollRestoration: true,
+ * });
+ *
+ * const { path, params } = useRoute();
+ * effect(() => {
+ *   console.log('Route changed:', path.value, params.value);
+ * });
+ *
+ * navigate('/user/42');
+ * ```
+ */
+
+export { BqLinkElement, registerBqLink } from './bq-link';
+export { interceptLinks, link } from './links';
+export { back, forward, navigate } from './navigation';
+export { createRouter } from './router';
+export { currentRoute } from './state';
+export type { NavigationGuard, Route, RouteDefinition, Router, RouterOptions } from './types';
+export { useRoute, type UseRouteReturn } from './use-route';
+export { isActive, isActiveSignal, resolve } from './utils';