@remix-run/router 0.1.0

package/router.d.ts

@@ -0,0 +1,298 @@
+import { History, Location, To } from "./history";
+import { Action as HistoryAction } from "./history";
+import { DataRouteObject, FormEncType, FormMethod, RouteMatch, RouteObject } from "./utils";
+/**
+ * Map of routeId -> data returned from a loader/action/error
+ */
+export interface RouteData {
+    [routeId: string]: any;
+}
+export interface DataRouteMatch extends RouteMatch<string, DataRouteObject> {
+}
+/**
+ * A Router instance manages all navigation and data loading/mutations
+ */
+export interface Router {
+    /**
+     * Return the current state of the router
+     */
+    get state(): RouterState;
+    /**
+     * Initialize the router, including adding history listeners and kicking off
+     * initial data fetches.  Returns a function to cleanup listeners and abort
+     * any in-progress loads
+     */
+    initialize(): Router;
+    /**
+     * Subscribe to router.state updates
+     *
+     * @param fn function to call with the new state
+     */
+    subscribe(fn: RouterSubscriber): () => void;
+    /**
+     * Enable scroll restoration behavior in the router
+     *
+     * @param savedScrollPositions Object that will manage positions, in case
+     *                             it's being restored from sessionStorage
+     * @param getScrollPosition    Function to get the active Y scroll position
+     * @param getKey               Function to get the key to use for restoration
+     */
+    enableScrollRestoration(savedScrollPositions: Record<string, number>, getScrollPosition: GetScrollPositionFunction, getKey?: GetScrollRestorationKeyFunction): () => void;
+    /**
+     * Navigate forward/backward in the history stack
+     * @param path Delta to move in the history stack
+     */
+    navigate(path: number): void;
+    /**
+     * Navigate to the given path
+     * @param path Path to navigate to
+     * @param opts Navigation options (method, submission, etc.)
+     */
+    navigate(path: To, opts?: NavigateOptions): void;
+    /**
+     * Trigger a fetcher load/submission
+     *
+     * @param key Fetcher key
+     * @param href href to fetch
+     * @param opts Fetcher options, (method, submission, etc.)
+     */
+    fetch(key: string, href: string, opts?: NavigateOptions): void;
+    /**
+     * Trigger a revalidation of all current route loaders and fetcher loads
+     */
+    revalidate(): void;
+    /**
+     * Utility function to create an href for the given location
+     * @param location
+     */
+    createHref(location: Location | URL): string;
+    /**
+     * Get/create a fetcher for the given key
+     * @param key
+     */
+    getFetcher<TData = any>(key?: string): Fetcher<TData>;
+    /**
+     * Delete the fetcher for a given key
+     * @param key
+     */
+    deleteFetcher(key?: string): void;
+    /**
+     * Cleanup listeners and abort any in-progress loads
+     */
+    dispose(): void;
+    /**
+     * Internal fetch AbortControllers accessed by unit tests
+     * @private
+     */
+    _internalFetchControllers: Map<string, AbortController>;
+}
+/**
+ * State maintained internally by the router.  During a navigation, all states
+ * reflect the the "old" location unless otherwise noted.
+ */
+export interface RouterState {
+    /**
+     * The action of the most recent navigation
+     */
+    historyAction: HistoryAction;
+    /**
+     * The current location reflected by the router
+     */
+    location: Location;
+    /**
+     * The current set of route matches
+     */
+    matches: DataRouteMatch[];
+    /**
+     * Tracks whether we've completed our initial data load
+     */
+    initialized: boolean;
+    /**
+     * Current scroll position we should start at for a new view
+     *  - number -> scroll position to restore to
+     *  - false -> do not restore scroll at all (used during submissions)
+     *  - null -> don't have a saved position, scroll to hash or top of page
+     */
+    restoreScrollPosition: number | false | null;
+    /**
+     * Indicate whether this navigation should reset the scroll position if we
+     * are unable to restore the scroll position
+     */
+    resetScrollPosition: boolean;
+    /**
+     * Tracks the state of the current navigation
+     */
+    navigation: Navigation;
+    /**
+     * Tracks any in-progress revalidations
+     */
+    revalidation: RevalidationState;
+    /**
+     * Data from the loaders for the current matches
+     */
+    loaderData: RouteData;
+    /**
+     * Data from the action for the current matches
+     */
+    actionData: RouteData | null;
+    /**
+     * Errors caught from loaders for the current matches
+     */
+    errors: RouteData | null;
+    /**
+     * Map of current fetchers
+     */
+    fetchers: Map<string, Fetcher>;
+}
+/**
+ * Data that can be passed into hydrate a Router from SSR
+ */
+export declare type HydrationState = Partial<Pick<RouterState, "loaderData" | "actionData" | "errors">>;
+/**
+ * Initialization options for createRouter
+ */
+export interface RouterInit {
+    routes: RouteObject[];
+    history: History;
+    hydrationData?: HydrationState;
+}
+/**
+ * Subscriber function signature for changes to router state
+ */
+export interface RouterSubscriber {
+    (state: RouterState): void;
+}
+/**
+ * Function signature for determining the key to be used in scroll restoration
+ * for a given location
+ */
+export interface GetScrollRestorationKeyFunction {
+    (location: Location, matches: DataRouteMatch[]): string | null;
+}
+/**
+ * Function signature for determining the current scroll position
+ */
+export interface GetScrollPositionFunction {
+    (): number;
+}
+/**
+ * Options for a navigate() call for a Link navigation
+ */
+declare type LinkNavigateOptions = {
+    replace?: boolean;
+    state?: any;
+};
+/**
+ * Options for a navigate() call for a Form navigation
+ */
+declare type SubmissionNavigateOptions = {
+    replace?: boolean;
+    state?: any;
+    formMethod?: FormMethod;
+    formEncType?: FormEncType;
+    formData: FormData;
+};
+/**
+ * Options to pass to navigate() for either a Link or Form navigation
+ */
+export declare type NavigateOptions = LinkNavigateOptions | SubmissionNavigateOptions;
+/**
+ * Potential states for state.navigation
+ */
+export declare type NavigationStates = {
+    Idle: {
+        state: "idle";
+        location: undefined;
+        formMethod: undefined;
+        formAction: undefined;
+        formEncType: undefined;
+        formData: undefined;
+    };
+    Loading: {
+        state: "loading";
+        location: Location;
+        formMethod: FormMethod | undefined;
+        formAction: string | undefined;
+        formEncType: FormEncType | undefined;
+        formData: FormData | undefined;
+    };
+    Submitting: {
+        state: "submitting";
+        location: Location;
+        formMethod: FormMethod;
+        formAction: string;
+        formEncType: FormEncType;
+        formData: FormData;
+    };
+};
+export declare type Navigation = NavigationStates[keyof NavigationStates];
+export declare type RevalidationState = "idle" | "loading";
+/**
+ * Potential states for fetchers
+ */
+declare type FetcherStates<TData = any> = {
+    Idle: {
+        state: "idle";
+        formMethod: undefined;
+        formAction: undefined;
+        formEncType: undefined;
+        formData: undefined;
+        data: TData | undefined;
+    };
+    Loading: {
+        state: "loading";
+        formMethod: FormMethod | undefined;
+        formAction: string | undefined;
+        formEncType: FormEncType | undefined;
+        formData: FormData | undefined;
+        data: TData | undefined;
+    };
+    Submitting: {
+        state: "submitting";
+        formMethod: FormMethod;
+        formAction: string;
+        formEncType: FormEncType;
+        formData: FormData;
+        data: TData | undefined;
+    };
+};
+export declare type Fetcher<TData = any> = FetcherStates<TData>[keyof FetcherStates<TData>];
+declare enum ResultType {
+    data = "data",
+    redirect = "redirect",
+    error = "error"
+}
+/**
+ * Successful result from a loader or action
+ */
+export interface SuccessResult {
+    type: ResultType.data;
+    data: any;
+}
+/**
+ * Redirect result from a loader or action
+ */
+export interface RedirectResult {
+    type: ResultType.redirect;
+    status: number;
+    location: string;
+    revalidate: boolean;
+}
+/**
+ * Unsuccessful result from a loader or action
+ */
+export interface ErrorResult {
+    type: ResultType.error;
+    error: any;
+}
+/**
+ * Result from a loader or action - potentially successful or unsuccessful
+ */
+export declare type DataResult = SuccessResult | RedirectResult | ErrorResult;
+export declare const IDLE_NAVIGATION: NavigationStates["Idle"];
+export declare const IDLE_FETCHER: FetcherStates["Idle"];
+/**
+ * Create a router and listen to history POP navigations
+ */
+export declare function createRouter(init: RouterInit): Router;
+export {};