@bquery/bquery 1.6.0 → 1.8.1

package/dist/router/bq-link.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `<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>
+ * ```
+ */
+/** @internal SSR-safe base class for environments without HTMLElement. */
+declare const BQ_LINK_BASE: {
+    new (): HTMLElement;
+    prototype: 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 declare class BqLinkElement extends BQ_LINK_BASE {
+    /** @internal */
+    private _cleanup;
+    /** @internal */
+    private _trackedActiveClasses;
+    static get observedAttributes(): string[];
+    /** The target path for navigation. */
+    get to(): string;
+    set to(value: string);
+    /** Whether to replace the current history entry. */
+    get replace(): boolean;
+    set replace(value: boolean);
+    /** Whether to match the path exactly for active class. */
+    get exact(): boolean;
+    set exact(value: boolean);
+    /** CSS class applied when the route is active. */
+    get activeClass(): string;
+    set activeClass(value: string);
+    /** @internal */
+    connectedCallback(): void;
+    /** @internal */
+    disconnectedCallback(): void;
+    /** @internal */
+    attributeChangedCallback(name: string, _oldValue: string | null, _newValue: string | null): void;
+    /**
+     * Sets up the reactive effect that toggles the active CSS class
+     * based on the current route.
+     * @internal
+     */
+    private _setupActiveTracking;
+    /** @internal */
+    private _clearTrackedActiveClasses;
+    /**
+     * Handles click events for SPA navigation.
+     * @internal
+     */
+    private _handleClick;
+    /**
+     * Handles keyboard activation (Enter).
+     * @internal
+     */
+    private _handleKeydown;
+    /**
+     * Performs the actual navigation.
+     * @internal
+     */
+    private _navigate;
+}
+/**
+ * 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 declare const registerBqLink: () => void;
+export {};
+//# sourceMappingURL=bq-link.d.ts.map

package/dist/router/bq-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bq-link.d.ts","sourceRoot":"","sources":["../../src/router/bq-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAoBH,0EAA0E;AAC1E,QAAA,MAAM,YAAY;;;CAC8E,CAAC;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,gBAAgB;IAChB,OAAO,CAAC,QAAQ,CAA0B;IAE1C,gBAAgB;IAChB,OAAO,CAAC,qBAAqB,CAA8B;IAE3D,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,sCAAsC;IACtC,IAAI,EAAE,IAAI,MAAM,CAGf;IAED,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAEnB;IAED,oDAAoD;IACpD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAMzB;IAED,0DAA0D;IAC1D,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,KAAK,CAAC,KAAK,EAAE,OAAO,EAMvB;IAED,kDAAkD;IAClD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAE5B;IAED,gBAAgB;IAChB,iBAAiB,IAAI,IAAI;IAmBzB,gBAAgB;IAChB,oBAAoB,IAAI,IAAI;IAY5B,gBAAgB;IAChB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAShG;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAuC5B,gBAAgB;IAChB,OAAO,CAAC,0BAA0B;IAOlC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAQlB;IAEF;;;OAGG;IACH,OAAO,CAAC,cAAc,CAKpB;IAEF;;;OAGG;IACH,OAAO,CAAC,SAAS;CASlB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,QAAO,IAQjC,CAAC"}

package/dist/router/constraints.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared helpers for validating and normalizing route param constraints.
+ * @internal
+ */
+export declare const getNormalizedRouteConstraint: (constraint: string) => string;
+export declare const getRouteConstraintRegex: (constraint: string) => RegExp;
+export declare const routeConstraintMatches: (constraint: string, value: string) => boolean;
+export declare const clearRouteConstraintCache: () => void;
+//# sourceMappingURL=constraints.d.ts.map

package/dist/router/constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraints.d.ts","sourceRoot":"","sources":["../../src/router/constraints.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2JH,eAAO,MAAM,4BAA4B,GAAI,YAAY,MAAM,KAAG,MASjE,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,YAAY,MAAM,KAAG,MAyB5D,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,YAAY,MAAM,EAAE,OAAO,MAAM,KAAG,OAE1E,CAAC;AAEF,eAAO,MAAM,yBAAyB,QAAO,IAG5C,CAAC"}

package/dist/router/index.d.ts

@@ -4,38 +4,46 @@
  * This module provides a lightweight, signal-based router for single-page
  * applications. Features include:
  * - History API navigation
- * - Route matching with params and wildcards
+ * - Route matching with params, wildcards, and regex constraints
  * - Lazy route loading
- * - Navigation guards (beforeEach, afterEach)
+ * - 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 } from 'bquery/router';
- * import { effect } from 'bquery/reactive';
+ * 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', component: () => import('./User') },
+ *     { 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:', currentRoute.value);
+ *   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 { currentRoute, isNavigating } from './state';
 export type { NavigationGuard, Route, RouteDefinition, Router, RouterOptions } from './types';
+export { useRoute, type UseRouteReturn } from './use-route';
 export { isActive, isActiveSignal, resolve } from './utils';
 //# sourceMappingURL=index.d.ts.map

package/dist/router/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,QAAQ,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC"}

package/dist/router/match.d.ts

@@ -5,7 +5,6 @@
 import type { Route, RouteDefinition } from './types';
 /**
  * Matches a path against route definitions and extracts params.
- * Uses positional captures for maximum compatibility.
  * @internal
  */
 export declare const matchRoute: (path: string, routes: RouteDefinition[]) => {

package/dist/router/match.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/router/match.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAmDtD;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,QAAQ,eAAe,EAAE,KACxB;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAmBjE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,UAAU,MAAM,EAChB,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,QAAQ,eAAe,EAAE,KACxB,KAUF,CAAC"}
+{"version":3,"file":"match.d.ts","sourceRoot":"","sources":["../../src/router/match.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAyQtD;;;GAGG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,QAAQ,eAAe,EAAE,KACxB;IAAE,OAAO,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,IAUjE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,UAAU,MAAM,EAChB,QAAQ,MAAM,EACd,MAAM,MAAM,EACZ,QAAQ,eAAe,EAAE,KACxB,KAUF,CAAC"}

package/dist/router/path-pattern.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared helpers for parsing route path params and constraints.
+ * @internal
+ */
+/** Validates whether a character can start a route param name. @internal */
+export declare const isParamStart: (char: string | undefined) => boolean;
+/** Validates whether a character can appear after the start of a route param name. @internal */
+export declare const isParamChar: (char: string | undefined) => boolean;
+/** Reads a route param constraint while preserving escaped chars and nested groups. @internal */
+export declare const readConstraint: (path: string, startIndex: number) => {
+    constraint: string;
+    endIndex: number;
+} | null;
+//# sourceMappingURL=path-pattern.d.ts.map

package/dist/router/path-pattern.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-pattern.d.ts","sourceRoot":"","sources":["../../src/router/path-pattern.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,4EAA4E;AAC5E,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,GAAG,SAAS,KAAG,OAEwB,CAAC;AAEjF,gGAAgG;AAChG,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,GAAG,SAAS,KAAG,OACmB,CAAC;AAE3E,iGAAiG;AACjG,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,YAAY,MAAM,KACjB;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAiC7C,CAAC"}

package/dist/router/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/router/query.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAmB3E,CAAC"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/router/query.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAoB3E,CAAC"}

package/dist/router/router.d.ts

@@ -17,10 +17,12 @@ import type { Router, RouterOptions } from './types';
  *   routes: [
  *     { path: '/', component: () => import('./pages/Home') },
  *     { path: '/about', component: () => import('./pages/About') },
- *     { path: '/user/:id', component: () => import('./pages/User') },
+ *     { path: '/user/:id(\\d+)', component: () => import('./pages/User') },
+ *     { path: '/old-page', redirectTo: '/new-page' },
  *     { path: '*', component: () => import('./pages/NotFound') },
  *   ],
  *   base: '/app',
+ *   scrollRestoration: true,
  * });
  *
  * router.beforeEach((to, from) => {

package/dist/router/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/router/router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAA0B,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAO7E;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,KAAG,MAyKrD,CAAC"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/router/router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,KAAK,EAA0B,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAoB7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,aAAa,KAAG,MAmWrD,CAAC"}

package/dist/router/state.d.ts

@@ -11,8 +11,8 @@ export declare const routeSignal: 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}`;
@@ -20,6 +20,29 @@ export declare const routeSignal: Signal<Route>;
  * ```
  */
 export declare const currentRoute: ReadonlySignal<Route>;
+/**
+ * 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 declare const isNavigating: ReadonlySignal<boolean>;
+/** @internal */
+export declare const beginNavigation: () => void;
+/** @internal */
+export declare const endNavigation: () => void;
+/** @internal */
+export declare const resetNavigationState: () => void;
 /** @internal */
 export declare const getActiveRouter: () => Router | null;
 /** @internal */

package/dist/router/state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/router/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAoB,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACvF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAS7C,gBAAgB;AAChB,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,KAAK,CAMpC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,KAAK,CAAqC,CAAC;AAErF,gBAAgB;AAChB,eAAO,MAAM,eAAe,QAAO,MAAM,GAAG,IAAoB,CAAC;AAEjE,gBAAgB;AAChB,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,GAAG,IAAI,KAAG,IAEvD,CAAC"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/router/state.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA8B,KAAK,cAAc,EAAE,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACjG,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAS7C,gBAAgB;AAChB,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,KAAK,CAMpC,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,KAAK,CAAqC,CAAC;AAQrF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,OAAO,CAAgC,CAAC;AAElF,gBAAgB;AAChB,eAAO,MAAM,eAAe,QAAO,IAKlC,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,aAAa,QAAO,IAOhC,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,oBAAoB,QAAO,IAGvC,CAAC;AAEF,gBAAgB;AAChB,eAAO,MAAM,eAAe,QAAO,MAAM,GAAG,IAAoB,CAAC;AAEjE,gBAAgB;AAChB,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,GAAG,IAAI,KAAG,IAEvD,CAAC"}

package/dist/router/types.d.ts

@@ -29,18 +29,55 @@ export type Route = {
 /**
  * Route definition for configuration.
  */
-export type RouteDefinition = {
-    /** Path pattern (e.g., '/user/:id', '/posts/*') */
+type BaseRouteDefinition = {
+    /**
+     * Path pattern (e.g., '/user/:id', '/posts/*').
+     * Supports regex constraints on params: `/user/:id(\\d+)`.
+     * Constraint backreferences are not supported.
+     */
     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[];
+    /**
+     * 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.
  */
@@ -51,6 +88,12 @@ export type RouterOptions = {
     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.
@@ -85,4 +128,5 @@ export type Router = {
     /** Destroy the router and cleanup listeners */
     destroy: () => void;
 };
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/router/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IACzC,mCAAmC;IACnC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAChC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,SAAS,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,iCAAiC;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;AAEnG;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,yBAAyB;IACzB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,oCAAoC;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,yBAAyB;IACzB,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,4BAA4B;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,qCAAqC;IACrC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,6BAA6B;IAC7B,UAAU,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,MAAM,IAAI,CAAC;IACnD,4BAA4B;IAC5B,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAClE,+BAA+B;IAC/B,YAAY,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IACpC,4BAA4B;IAC5B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/router/types.ts"],"names":[],"mappings":"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"}

package/dist/router/use-route.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Reactive route composable.
+ * @module bquery/router
+ */
+import { type ReadonlySignal } from '../reactive/index';
+import type { Route, RouteDefinition } from './types';
+/**
+ * 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>;
+};
+/**
+ * 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 declare const useRoute: () => UseRouteReturn;
+//# sourceMappingURL=use-route.d.ts.map

package/dist/router/use-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-route.d.ts","sourceRoot":"","sources":["../../src/router/use-route.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAMtD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,iCAAiC;IACjC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IAC7B,4BAA4B;IAC5B,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,4BAA4B;IAC5B,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,4BAA4B;IAC5B,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,yCAAyC;IACzC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAC7B,wCAAwC;IACxC,OAAO,EAAE,cAAc,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;CACjD,CAAC;AAWF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,QAAQ,QAAO,cAE3B,CAAC"}

package/dist/router/utils.d.ts

@@ -16,6 +16,9 @@ export declare const flattenRoutes: (routes: RouteDefinition[], parentPath?: str
  * @param name - The route name
  * @param params - Route params to interpolate
  * @returns The resolved path
+ * @throws {Error} If no router is initialized, the route name is unknown,
+ * a required path param is missing from `params`, a param value does not satisfy
+ * its route regex constraint, or a route param constraint has invalid syntax
  *
  * @example
  * ```ts

package/dist/router/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/router/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,eAAe,EAAE,EAAE,mBAAe,KAAG,eAAe,EAiBzF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,SAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,KAAG,MAiB3E,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,eAAa,KAAG,OAGtD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,eAAa,KAAG,cAAc,CAAC,OAAO,CAKlF,CAAC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/router/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIlE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAM/C;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,eAAe,EAAE,EAAE,mBAAe,KAAG,eAAe,EAiBzF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,EAAE,SAAQ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,KAAG,MAqD3E,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,QAAQ,GAAI,MAAM,MAAM,EAAE,eAAa,KAAG,OAGtD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,eAAa,KAAG,cAAc,CAAC,OAAO,CAKlF,CAAC"}