@bquery/bquery 1.7.0 → 1.8.2

package/src/router/state.ts

@@ -3,7 +3,7 @@
  * @module bquery/router
  */
 
-import { computed, signal, type ReadonlySignal, type Signal } from '../reactive/index';
+import { computed, readonly, signal, type ReadonlySignal, type Signal } from '../reactive/index';
 import type { Route, Router } from './types';
 
 // ============================================================================
@@ -27,8 +27,8 @@ export const routeSignal: Signal<Route> = signal<Route>({
  *
  * @example
  * ```ts
- * import { currentRoute } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
+ * import { currentRoute } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
  *
  * effect(() => {
  *   document.title = `Page: ${currentRoute.value.path}`;
@@ -37,6 +37,54 @@ export const routeSignal: Signal<Route> = signal<Route>({
  */
 export const currentRoute: ReadonlySignal<Route> = computed(() => routeSignal.value);
 
+/** @internal */
+const navigationCountSignal: Signal<number> = signal(0);
+
+/** @internal */
+const isNavigatingSignal: Signal<boolean> = signal(false);
+
+/**
+ * Reactive signal indicating whether a navigation is currently in progress.
+ *
+ * This becomes `true` while async guards or redirect resolution are running,
+ * then flips back to `false` once navigation finishes or is canceled.
+ *
+ * @example
+ * ```ts
+ * import { isNavigating } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * effect(() => {
+ *   document.body.toggleAttribute('data-loading-route', isNavigating.value);
+ * });
+ * ```
+ */
+export const isNavigating: ReadonlySignal<boolean> = readonly(isNavigatingSignal);
+
+/** @internal */
+export const beginNavigation = (): void => {
+  if (navigationCountSignal.value === 0) {
+    isNavigatingSignal.value = true;
+  }
+  navigationCountSignal.value += 1;
+};
+
+/** @internal */
+export const endNavigation = (): void => {
+  const nextCount = Math.max(0, navigationCountSignal.value - 1);
+  navigationCountSignal.value = nextCount;
+
+  if (nextCount === 0) {
+    isNavigatingSignal.value = false;
+  }
+};
+
+/** @internal */
+export const resetNavigationState = (): void => {
+  navigationCountSignal.value = 0;
+  isNavigatingSignal.value = false;
+};
+
 /** @internal */
 export const getActiveRouter = (): Router | null => activeRouter;
 

package/src/router/types.ts

@@ -1,139 +1,139 @@
-/**
- * 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.
- */
-type BaseRouteDefinition = {
-  /**
-   * Path pattern (e.g., '/user/:id', '/posts/*').
-   * Supports regex constraints on params: `/user/:id(\\d+)`.
-   * Constraint backreferences are not supported.
-   */
-  path: string;
-  /** Optional route name for programmatic navigation */
-  name?: string;
-  /** Optional metadata */
-  meta?: Record<string, unknown>;
-  /** Nested child routes */
-  children?: RouteDefinition[];
-  /**
-   * Per-route navigation guard. Called before entering this route.
-   * Return `false` to cancel navigation.
-   *
-   * @example
-   * ```ts
-   * {
-   *   path: '/admin',
-   *   component: () => import('./Admin'),
-   *   beforeEnter: (to, from) => isAuthenticated() || false,
-   * }
-   * ```
-   */
-  beforeEnter?: NavigationGuard;
-};
-
-type ComponentRouteDefinition = BaseRouteDefinition & {
-  /** Component loader (sync or async) */
-  component: () => unknown | Promise<unknown>;
-  redirectTo?: never;
-};
-
-type RedirectRouteDefinition = BaseRouteDefinition & {
-  /**
-   * Redirect target path. When the route is matched, the router
-   * automatically navigates to this path instead.
-   *
-   * @example
-   * ```ts
-   * { path: '/old-page', redirectTo: '/new-page' }
-   * ```
-   */
-  redirectTo: string;
-  component?: never;
-  children?: never;
-  beforeEnter?: never;
-};
-
-export type RouteDefinition = ComponentRouteDefinition | RedirectRouteDefinition;
-
-/**
- * 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;
-  /**
-   * Restore scroll position on back/forward navigation (default: false).
-   * When enabled, the router saves scroll positions for each history entry
-   * and restores them on popstate events.
-   */
-  scrollRestoration?: 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;
-};
+/**
+ * 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.
+ */
+type BaseRouteDefinition = {
+  /**
+   * Path pattern (e.g., '/user/:id', '/posts/*').
+   * Supports regex constraints on params: `/user/:id(\\d+)`.
+   * Constraint backreferences are not supported.
+   */
+  path: string;
+  /** Optional route name for programmatic navigation */
+  name?: string;
+  /** Optional metadata */
+  meta?: Record<string, unknown>;
+  /** Nested child routes */
+  children?: RouteDefinition[];
+  /**
+   * Per-route navigation guard. Called before entering this route.
+   * Return `false` to cancel navigation.
+   *
+   * @example
+   * ```ts
+   * {
+   *   path: '/admin',
+   *   component: () => import('./Admin'),
+   *   beforeEnter: (to, from) => isAuthenticated() || false,
+   * }
+   * ```
+   */
+  beforeEnter?: NavigationGuard;
+};
+
+type ComponentRouteDefinition = BaseRouteDefinition & {
+  /** Component loader (sync or async) */
+  component: () => unknown | Promise<unknown>;
+  redirectTo?: never;
+};
+
+type RedirectRouteDefinition = BaseRouteDefinition & {
+  /**
+   * Redirect target path. When the route is matched, the router
+   * automatically navigates to this path instead.
+   *
+   * @example
+   * ```ts
+   * { path: '/old-page', redirectTo: '/new-page' }
+   * ```
+   */
+  redirectTo: string;
+  component?: never;
+  children?: never;
+  beforeEnter?: never;
+};
+
+export type RouteDefinition = ComponentRouteDefinition | RedirectRouteDefinition;
+
+/**
+ * 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;
+  /**
+   * Restore scroll position on back/forward navigation (default: false).
+   * When enabled, the router saves scroll positions for each history entry
+   * and restores them on popstate events.
+   */
+  scrollRestoration?: 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;
+};

package/src/router/use-route.ts

@@ -1,68 +1,68 @@
-/**
- * Reactive route composable.
- * @module bquery/router
- */
-
-import { computed, type ReadonlySignal } from '../reactive/index';
-import { routeSignal } from './state';
-import type { Route, RouteDefinition } from './types';
-
-// ============================================================================
-// useRoute Composable
-// ============================================================================
-
-/**
- * Return type for {@link useRoute}.
- * Provides reactive access to individual route properties.
- */
-export type UseRouteReturn = {
-  /** Full reactive route object */
-  route: ReadonlySignal<Route>;
-  /** Reactive current path */
-  path: ReadonlySignal<string>;
-  /** Reactive route params */
-  params: ReadonlySignal<Record<string, string>>;
-  /** Reactive query params */
-  query: ReadonlySignal<Record<string, string | string[]>>;
-  /** Reactive hash fragment (without #) */
-  hash: ReadonlySignal<string>;
-  /** Reactive matched route definition */
-  matched: ReadonlySignal<RouteDefinition | null>;
-};
-
-const route = computed(() => routeSignal.value);
-const path = computed(() => route.value.path);
-const params = computed(() => route.value.params);
-const query = computed(() => route.value.query);
-const hash = computed(() => route.value.hash);
-const matched = computed(() => route.value.matched);
-
-const routeHandle: UseRouteReturn = { route, path, params, query, hash, matched };
-
-/**
- * Returns reactive access to the current route, params, query, and hash.
- *
- * Each property is a readonly computed signal that updates automatically
- * when the route changes. This is useful for fine-grained reactivity
- * where you only need to subscribe to specific route parts.
- *
- * @returns An object with reactive route properties
- *
- * @example
- * ```ts
- * import { useRoute } from '@bquery/bquery/router';
- * import { effect } from '@bquery/bquery/reactive';
- *
- * const { path, params, query, hash } = useRoute();
- *
- * effect(() => {
- *   console.log('Path:', path.value);
- *   console.log('Params:', params.value);
- *   console.log('Query:', query.value);
- *   console.log('Hash:', hash.value);
- * });
- * ```
- */
-export const useRoute = (): UseRouteReturn => {
-  return routeHandle;
-};
+/**
+ * Reactive route composable.
+ * @module bquery/router
+ */
+
+import { computed, type ReadonlySignal } from '../reactive/index';
+import { routeSignal } from './state';
+import type { Route, RouteDefinition } from './types';
+
+// ============================================================================
+// useRoute Composable
+// ============================================================================
+
+/**
+ * Return type for {@link useRoute}.
+ * Provides reactive access to individual route properties.
+ */
+export type UseRouteReturn = {
+  /** Full reactive route object */
+  route: ReadonlySignal<Route>;
+  /** Reactive current path */
+  path: ReadonlySignal<string>;
+  /** Reactive route params */
+  params: ReadonlySignal<Record<string, string>>;
+  /** Reactive query params */
+  query: ReadonlySignal<Record<string, string | string[]>>;
+  /** Reactive hash fragment (without #) */
+  hash: ReadonlySignal<string>;
+  /** Reactive matched route definition */
+  matched: ReadonlySignal<RouteDefinition | null>;
+};
+
+const route = computed(() => routeSignal.value);
+const path = computed(() => route.value.path);
+const params = computed(() => route.value.params);
+const query = computed(() => route.value.query);
+const hash = computed(() => route.value.hash);
+const matched = computed(() => route.value.matched);
+
+const routeHandle: UseRouteReturn = { route, path, params, query, hash, matched };
+
+/**
+ * Returns reactive access to the current route, params, query, and hash.
+ *
+ * Each property is a readonly computed signal that updates automatically
+ * when the route changes. This is useful for fine-grained reactivity
+ * where you only need to subscribe to specific route parts.
+ *
+ * @returns An object with reactive route properties
+ *
+ * @example
+ * ```ts
+ * import { useRoute } from '@bquery/bquery/router';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const { path, params, query, hash } = useRoute();
+ *
+ * effect(() => {
+ *   console.log('Path:', path.value);
+ *   console.log('Params:', params.value);
+ *   console.log('Query:', query.value);
+ *   console.log('Hash:', hash.value);
+ * });
+ * ```
+ */
+export const useRoute = (): UseRouteReturn => {
+  return routeHandle;
+};