ranui/dist/utils/router/index.d.ts

A framework-agnostic Web Components UI library built on native custom elements, with TypeScript types, light/dark theming, SSR and PWA support.

export interface RouteConfig {
    path: string;
    exact?: boolean;
    meta?: Record<string, unknown>;
    children?: RouteConfig[];
}
export type ViewTransitionMode = 'spa' | 'mpa' | 'both';
export interface RouterConfig {
    mode?: 'history' | 'hash';
    base?: string;
    routes?: RouteConfig[];
    /**
     * Enable View Transitions API.
     *
     * - `'spa'` / `true`  — wraps same-document DOM updates in document.startViewTransition().
     * - `'mpa'`           — injects `@view-transition { navigation: auto }` for cross-document
     *                       transitions; hooks pageswap/pagereveal for customization.
     * - `'both'`          — spa + mpa combined; best for apps that do both client-side and
     *                       full-page navigation.
     *
     * Gracefully degrades when the API is not supported.
     */
    viewTransition?: boolean | ViewTransitionMode;
}
export interface RouteLocation {
    path: string;
    params: Record<string, string>;
    query: Record<string, string>;
    fullPath: string;
}
export type NavigationGuard = (to: RouteLocation, from: RouteLocation | null, next: (redirect?: string | false) => void) => void;
export type RouteChangeHandler = (to: RouteLocation, from: RouteLocation | null) => void;
export interface PageSwapEvent extends Event {
    readonly viewTransition: ViewTransitionHandle | null;
    readonly activation: NavigationActivation | null;
}
export interface PageRevealEvent extends Event {
    readonly viewTransition: ViewTransitionHandle | null;
}
interface NavigationActivation {
    readonly entry: unknown;
    readonly from: unknown;
    readonly navigationType: string;
}
interface ViewTransitionHandle {
    readonly ready: Promise<void>;
    readonly finished: Promise<void>;
    readonly updateCallbackDone: Promise<void>;
    skipTransition(): void;
    types?: Set<string>;
}
export interface RouterComponentElement extends HTMLElement {
    _syncRoutes(): void;
}
export declare function getSSGPath(): string | null;
export declare function setSSGPath(path: string): void;
export declare function clearSSGPath(): void;
/**
 * Match a route pattern (with `:param` and `*` segments) against a path.
 * Single source of truth shared by RouterCore and the `<r-route>` element.
 */
export declare function matchPath(routePath: string, exact: boolean, path: string): {
    matched: boolean;
    params: Record<string, string>;
};
export declare class RouterCore {
    private readonly _mode;
    private readonly _base;
    private readonly _routes;
    private readonly _flatRoutes;
    private readonly _vtMode;
    private readonly _beforeGuards;
    private readonly _afterGuards;
    private readonly _changeHandlers;
    private readonly _pageSwapHandlers;
    private readonly _pageRevealHandlers;
    private readonly _components;
    private _current;
    private _mpaActive;
    constructor(config?: RouterConfig);
    get mode(): 'history' | 'hash';
    get base(): string;
    get routes(): RouteConfig[];
    get currentRoute(): RouteLocation | null;
    /** Return the first matching route (absolute path, nested-aware), or null. */
    matchRoute(path: string): RouteConfig | null;
    /** Extract `:param` values for the first matching route ({} if none). */
    matchParams(path: string): Record<string, string>;
    /** All declared route paths (nested flattened) — used to enumerate SSG pages. */
    getStaticPaths(): string[];
    private _enableMpa;
    private _disableMpa;
    private _onPageSwap;
    private _onPageReveal;
    _bind(component: RouterComponentElement): void;
    _unbind(component: RouterComponentElement): void;
    _buildLocation(path: string): RouteLocation;
    _getCurrentPath(): string;
    _notify(): void;
    private _navigate;
    push(path: string): Promise<void>;
    replace(path: string): Promise<void>;
    back(): void;
    forward(): void;
    go(delta: number): void;
    /** Tear down MPA listeners and injected CSS. Call when the router is no longer needed. */
    destroy(): void;
    /** Register a navigation guard. Returns an unsubscribe function. */
    beforeEach(guard: NavigationGuard): () => void;
    /** Register a post-navigation hook. Returns an unsubscribe function. */
    afterEach(handler: RouteChangeHandler): () => void;
    /** Subscribe to route changes. Returns an unsubscribe function. */
    onRouteChange(handler: RouteChangeHandler): () => void;
    /**
     * Subscribe to the cross-document `pageswap` event (fires on the outgoing page).
     * Only active when viewTransition is 'mpa' or 'both'.
     * Returns an unsubscribe function.
     */
    onPageSwap(handler: (e: PageSwapEvent) => void): () => void;
    /**
     * Subscribe to the cross-document `pagereveal` event (fires on the incoming page).
     * Only active when viewTransition is 'mpa' or 'both'.
     * Returns an unsubscribe function.
     */
    onPageReveal(handler: (e: PageRevealEvent) => void): () => void;
}
/** Create and register a global RouterCore instance. */
export declare function createRouter(config?: RouterConfig): RouterCore;
/** Return the current global RouterCore instance, or null if none was created. */
export declare function useRouter(): RouterCore | null;
/**
 * Standalone helper — enable cross-document View Transitions without a router.
 * Injects `@view-transition { navigation: auto }` once and returns a cleanup function.
 *
 * Useful for pure MPA sites that don't need a JS router at all.
 */
export declare function enableMpaViewTransitions(): () => void;
export {};