@simplux/browser-router/simplux-browser-router.d.ts

The browser router package for simplux. Can be used to provide routing capabilities to a web app.

import type { Immutable } from '@simplux/core';
import { NavigateToFn } from '@simplux/router';
import { NAVIGATION_CANCELLED } from '@simplux/router';
import { NAVIGATION_FINISHED } from '@simplux/router';
import { NavigationParameters } from '@simplux/router';
import { NavigationResult } from '@simplux/router';
import { OnNavigateTo } from '@simplux/router';
import { OnNavigateToExtras } from '@simplux/router';
import { RequiredPropertyNames } from '@simplux/router';
import type { _RouteId } from '@simplux/router';
import { SIMPLUX_ROUTE } from '@simplux/router';
import { SimpluxEffect } from '@simplux/core';
import { SimpluxRoute } from '@simplux/router';
import { SimpluxRouteConfiguration } from '@simplux/router';
import { SimpluxRouterSelectors } from '@simplux/router';
import { SimpluxSelector } from '@simplux/core';

/**
 * Get the simplux browser router.
 *
 * @public
 */
export declare function getSimpluxBrowserRouter(): SimpluxBrowserRouter;

/**
 * Helper type to specify the parameters for an href selector
 *
 * @public
 */
export declare type HrefSelectorParameters<TParameters> = keyof TParameters extends never ? [] : RequiredPropertyNames<TParameters> extends never ? [parameters: TParameters] | [] : [parameters: TParameters];

export { NavigateToFn }

export { NAVIGATION_CANCELLED }

export { NAVIGATION_FINISHED }

export { NavigationParameters }

export { NavigationResult }

export { OnNavigateTo }

export { OnNavigateToExtras }

/**
 * Helper type to distinguish parameter name values.
 *
 * @public
 */
export declare type _ParameterName = string;

/**
 * Helper type to distinguish parameter type values.
 *
 * @public
 */
export declare type _ParameterType = 'string' | 'number' | 'boolean' | 'string[]' | 'number[]' | 'boolean[]';

/**
 * Helper type to parse a parameter template.
 *
 * @public
 */
export declare type _ParseParameter<TTemplate, TPrefix extends string = ''> = TTemplate extends `${TPrefix}${infer TName}:${infer TType}` ? {
    [name in TName]: _ParseParameterType<TType>;
} : TTemplate extends `${TPrefix}${infer TName}` ? {
    [name in TName]: string;
} : {};

/**
 * Helper type to parse the type of a parameter from a parameter template.
 *
 * @public
 */
export declare type _ParseParameterType<T> = T extends `${infer TItem}[]` ? _ParseParameterType<TItem>[] : T extends `string` ? string : T extends `number` ? number : T extends `boolean` ? boolean : T;

/**
 * Helper type to parse parameters from a path template.
 *
 * @public
 */
export declare type _ParsePathParameters<TTemplate> = TTemplate extends `${infer TSegment}/${infer TRest}` ? _ParseParameter<TSegment, ':'> & _ParsePathParameters<TRest> : _ParseParameter<TTemplate, ':'>;

/**
 * Helper type to parse parameters from a query template.
 *
 * @public
 */
export declare type _ParseQueryParameters<TTemplate extends string> = TTemplate extends `${infer TSegment}[&${infer TRest}]` ? _ParseParameter<TSegment> & Partial<_ParseQueryParameters<TRest>> : TTemplate extends `${infer TSegment}&${infer TRest}` ? _ParseParameter<TSegment> & _ParseQueryParameters<TRest> : _ParseParameter<TTemplate>;

export { RequiredPropertyNames }

export { SIMPLUX_ROUTE }

/**
 * A simplux browser route.
 *
 * @public
 */
export declare interface SimpluxBrowserRoute<TParameters, TConfiguration extends SimpluxRouteConfiguration<TParameters> = {}> extends Omit<SimpluxRoute<TParameters, TConfiguration>, 'addChildRoute'> {
    /**
     * Helper property to get the parameter type of this route via
     * `typeof route.$parameterTypes`. Will be `undefined` at runtime.
     */
    readonly $parameterTypes: TParameters;
    /**
     * A selector for generating an href value for the route with the given
     * parameters.
     *
     * @param parameters - the parameters for the navigation (if the route has any)
     *
     * @returns an href string that can be used to link to this route (e.g.
     * in HTML anchors)
     */
    readonly href: SimpluxSelector<never, HrefSelectorParameters<TParameters>, string>;
    /**
     * Add a child route with the given template to the route. The child
     * route's template will be the concatenation of this route's template
     * and the child's template.
     *
     * Parameter types are automatically parsed from the template.
     *
     * @param template - the template of the route
     * @param routeConfiguration - configuration for the route
     *
     * @returns a route object for interacting with the child route
     */
    readonly addChildRoute: SimpluxEffect<(<TUrlTemplate extends string, TConfiguration extends SimpluxBrowserRouteConfiguration<{
        [p in keyof (TemplateParameters<TUrlTemplate> & TParameters)]: (TemplateParameters<TUrlTemplate> & TParameters)[p];
    }>>(template: TUrlTemplate, routeConfiguration?: TConfiguration) => SimpluxBrowserRoute<{
        [p in keyof (TemplateParameters<TUrlTemplate> & TParameters)]: (TemplateParameters<TUrlTemplate> & TParameters)[p];
    }, TConfiguration>)>;
}

/**
 * The configuration for a browser route.
 *
 * @public
 */
export declare interface SimpluxBrowserRouteConfiguration<TParameters> extends SimpluxRouteConfiguration<TParameters> {
}

/**
 * A router that allows navigating between different routes by
 * using the browser URL.
 *
 * @public
 */
export declare interface SimpluxBrowserRouter extends SimpluxRouterSelectors {

    /**
     * A selector to get the URL of the current navigation (if a navigation
     * is currently ongoing). Useful for remembering the URL when redirecting
     * to a different route inside `onNavigateTo`.
     *
     * @returns the URL of the current navigation if a navigation is currently
     * ongoing, otherwise `undefined`
     */
    readonly currentNavigationUrl: SimpluxSelector<never, [], string | undefined>;
    /**
     * Add a new route with the given template to the router.
     *
     * Parameter types are automatically parsed from the template.
     *
     * @param template - the template of the route
     * @param routeConfiguration - configuration for the route
     *
     * @returns a route object for interacting with the route
     */
    readonly addRoute: SimpluxEffect<(<TUrlTemplate extends string, TConfiguration extends SimpluxBrowserRouteConfiguration<{
        [p in keyof TemplateParameters<TUrlTemplate>]: TemplateParameters<TUrlTemplate>[p];
    }>>(template: TUrlTemplate, routeConfiguration?: TConfiguration) => SimpluxBrowserRoute<{
        [p in keyof TemplateParameters<TUrlTemplate>]: TemplateParameters<TUrlTemplate>[p];
    }, TConfiguration>)>;
    /**
     * Navigate to a URL. Does the same as if the URL was entered in the
     * browser address bar. The URL is treated as relative to your site root,
     * i.e. the URL is always prefixed with `/` if it is not already.
     *
     * @param url - URL to navigate to
     *
     * @returns the result of the navigation
     */
    readonly navigateToUrl: SimpluxEffect<(url: string) => NavigationResult>;
    /**
     * Connect the router to the browser window. The router will start
     * listening to location changes and will update the location on
     * route navigations.
     *
     * @param window - the window object
     *
     * @returns a function that can be called to deactivate the router
     */
    readonly activate: SimpluxEffect<(window: Window) => () => void>;
}

export { SimpluxRoute }

export { SimpluxRouteConfiguration }

export { SimpluxRouterSelectors }

/**
 * Helper type to parse parameters from a URL template.
 *
 * @public
 */
export declare type TemplateParameters<TUrlTemplate extends _UrlTemplate> = TUrlTemplate extends `${infer TPathTemplate}[?${infer TQueryTemplate}]` ? _ParsePathParameters<TPathTemplate> & Partial<_ParseQueryParameters<TQueryTemplate>> : TUrlTemplate extends `${infer TPathTemplate}?${infer TQueryTemplate}` ? _ParsePathParameters<TPathTemplate> & _ParseQueryParameters<TQueryTemplate> : _ParsePathParameters<TUrlTemplate>;

/**
 * Helper type to distinguish url template values.
 *
 * @public
 */
export declare type _UrlTemplate = string;

export { }