@remix-run/router 0.1.0

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) React Training 2015-2019
+Copyright (c) Remix Software 2020-2022
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# Router
+
+The `@remix-run/router` package is the heart of [React Router](https://github.com/remix-run/react-router) and provides all the core functionality for routing, data loading, data mutations, and navigation.
+
+If you're using React Router, you should never `import` anything directly from
+the `@remix-run/router` or `react-router` packages, but you should have everything
+you need in either `react-router-dom` or `react-router-native`. Both of those
+packages re-export everything from `@remix-run/router` and `react-router`.
+
+## API
+
+A Router instance can be created using `createRouter`:
+
+```js
+let router = createRouter({
+  // Routes array using react-router RouteObject's
+  routes,
+  // History instance
+  history,
+  // Callback function executed on every state change
+  onChange: (state) => { ... },
+  // Optional hydration data for SSR apps
+  hydrationData?: HydrationState;
+}
+```
+
+Internally, the Router represents the state in an object of the following format, which is available through `router.state` or via the `onChange` callback function:
+
+```ts
+interface RouterState {
+  // The `history` action of the most recently completed navigation
+  action: Action;
+  // The current location of the router.  During a navigation this reflects
+  // the "old" location and is updated upon completion of the navigation
+  location: Location;
+  // The current set of route matches
+  matches: RouteMatch[];
+  // The state of the current navigation
+  navigation: Navigation;
+  // Data from the loaders for the current matches
+  loaderData: RouteData;
+  // Data from the action for the current matches
+  actionData: RouteData | null;
+  // Errors thrown from loaders/actions for the current matches
+  errors: RouteData | null;
+}
+```
+
+### Navigations
+
+All navigations are done through the `router.navigate` API which is overloaded to support different types of navigations:
+
+```js
+// Link navigation (pushes onto the history stack by default)
+router.navigate('/page');
+
+// Link navigation (replacing the history stack)
+router.navigate('/page', { replace: true });
+
+// Pop navigation (moving backward/forward in the history stack)
+router.navigate(-1);
+
+// Form navigation
+router.navigate('/page', {
+  formMethod: 'GET',
+  formData: new FormData(...),
+});
+```
+
+## Navigation Flows
+
+Each navigation (link click or form submission) in the Router is reflected via an internal `state.navigation` that indicates the state of the navigation. This concept of a `navigation` is a complex and heavily async bit of logic that is foundational to the Router's ability to manage data loading, submission, error handling, redirects, interruptions, and so on. Due to the user-driven nature of interruptions we don't quite believe it can be modeled as a finite state machine, however we have modeled some of the happy path flows below for clarity.
+
+_Note: This does not depict error or interruption flows._
+
+```mermaid
+graph LR
+  %% Link click
+  idle -->|link clicked| loading/normalLoad
+  subgraph "<Link> click"
+  loading/normalLoad -->|loader redirected| loading/normalRedirect
+  loading/normalRedirect --> loading/normalRedirect
+  end
+  loading/normalLoad -->|loaders completed| idle
+  loading/normalRedirect -->|loaders completed| idle
+
+  %% Form method=get
+  idle -->|form method=get| submitting/loaderSubmission
+  subgraph "<Form method=get>"
+  submitting/loaderSubmission -->|loader redirected| R1[loading/submissionRedirect]
+  R1[loading/submissionRedirect] --> R1[loading/submissionRedirect]
+  end
+  submitting/loaderSubmission -->|loaders completed| idle
+  R1[loading/submissionRedirect] -->|loaders completed| idle
+
+  %% Form method=post
+  idle -->|form method=post| submitting/actionSubmission
+  subgraph "<Form method=post>"
+  submitting/actionSubmission -->|action returned| loading/actionReload
+  submitting/actionSubmission -->|action redirected| R2[loading/submissionRedirect]
+  loading/actionReload -->|loader redirected| R2[loading/submissionRedirect]
+  R2[loading/submissionRedirect] --> R2[loading/submissionRedirect]
+  end
+  loading/actionReload -->|loaders completed| idle
+  R2[loading/submissionRedirect] -->|loaders completed| idle
+
+  idle -->|fetcher action redirect| R3[loading/submissionRedirect]
+  subgraph "Fetcher action redirect"
+  R3[loading/submissionRedirect] --> R3[loading/submissionRedirect]
+  end
+  R3[loading/submissionRedirect] -->|loaders completed| idle
+```
+
+## Fetcher Flows
+
+Fetcher submissions and loads in the Router can each have their own internal states, indicated on `fetcher.state` and `fetcher.type`. As with navigations, these states are a complex and heavily async bit of logic that is foundational to the Router's ability to manage data loading, submission, error handling, redirects, interruptions, and so on. Due to the user-driven nature of interruptions we don't quite believe it can be modeled as a finite state machine, however we have modeled some of the happy path flows below for clarity.
+
+_Note: This does not depict error or interruption flows, nor the ability to re-use fetchers once they've reached `idle/done`._
+
+```mermaid
+graph LR
+  idle/init -->|"load"| loading/normalLoad
+  subgraph "Normal Fetch"
+  loading/normalLoad -.->|loader redirected| T1{{navigation}}
+  end
+  loading/normalLoad -->|loader completed| idle/done
+  T1{{navigation}} -.-> idle/done
+
+  idle/init -->|"submit (get)"| submitting/loaderSubmission
+  subgraph "Loader Submission"
+  submitting/loaderSubmission -.->|"loader redirected"| T2{{navigation}}
+  end
+  submitting/loaderSubmission -->|loader completed| idle/done
+  T2{{navigation}} -.-> idle/done
+
+  idle/init -->|"submit (post)"| submitting/actionSubmission
+  subgraph "Action Submission"
+  submitting/actionSubmission -->|action completed| loading/actionReload
+  submitting/actionSubmission -->|action redirected| loading/submissionRedirect
+  loading/submissionRedirect -.-> T3{{navigation}}
+  loading/actionReload -.-> |loaders redirected| T3{{navigation}}
+  end
+  T3{{navigation}} -.-> idle/done
+  loading/actionReload --> |loaders completed| idle/done
+
+  idle/done -->|"revalidate"| loading/revalidate
+  subgraph "Fetcher Revalidation"
+  loading/revalidate -.->|loader redirected| T4{{navigation}}
+  end
+  loading/revalidate -->|loader completed| idle/done
+  T4{{navigation}} -.-> idle/done
+
+  classDef navigation fill:lightgreen;
+  class T1,T2,T3,T4 navigation;
+```

package/__tests__/TestSequences/EncodedReservedCharacters.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function EncodeReservedCharacters(history: History): void;

package/__tests__/TestSequences/GoBack.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function GoBack(history: History): Promise<void>;

package/__tests__/TestSequences/GoForward.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function GoForward(history: History): Promise<void>;

package/__tests__/TestSequences/InitialLocationDefaultKey.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function InitialLocationDefaultKey(history: History): void;

package/__tests__/TestSequences/InitialLocationHasKey.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function InitialLocationHasKey(history: History): void;

package/__tests__/TestSequences/Listen.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function Listen(history: History): void;

package/__tests__/TestSequences/ListenPopOnly.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function ListenPopOnly(history: History): void;

package/__tests__/TestSequences/PushMissingPathname.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushMissingPathname(history: History): void;

package/__tests__/TestSequences/PushNewLocation.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushNewLocation(history: History): void;

package/__tests__/TestSequences/PushRelativePathname.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushRelativePathname(history: History): void;

package/__tests__/TestSequences/PushRelativePathnameWarning.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushRelativePathnameWarning(history: History): void;

package/__tests__/TestSequences/PushSamePath.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushSamePath(history: History): Promise<void>;

package/__tests__/TestSequences/PushState.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function PushState(history: History): void;

package/__tests__/TestSequences/ReplaceNewLocation.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function ReplaceNewLocation(history: History): void;

package/__tests__/TestSequences/ReplaceSamePath.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function ReplaceSamePath(history: History): void;

package/__tests__/TestSequences/ReplaceState.d.ts

@@ -0,0 +1,2 @@
+import type { History } from "../../history";
+export default function ReplaceState(history: History): void;

package/__tests__/browser-test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment ./__tests__/custom-environment.js
+ */
+export {};

package/__tests__/create-path-test.d.ts

@@ -0,0 +1 @@
+export {};

package/__tests__/hash-base-test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment ./__tests__/custom-environment.js
+ */
+export {};

package/__tests__/hash-test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment ./__tests__/custom-environment.js
+ */
+export {};

package/__tests__/memory-test.d.ts

@@ -0,0 +1 @@
+export {};

package/__tests__/router-test.d.ts

@@ -0,0 +1,2 @@
+export declare function invariant(value: boolean, message?: string): asserts value;
+export declare function invariant<T>(value: T | null | undefined, message?: string): asserts value is T;

package/__tests__/setup.d.ts

@@ -0,0 +1 @@
+export {};

package/history.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Actions represent the type of change to a location value.
+ */
+export declare enum Action {
+    /**
+     * A POP indicates a change to an arbitrary index in the history stack, such
+     * as a back or forward navigation. It does not describe the direction of the
+     * navigation, only that the current index changed.
+     *
+     * Note: This is the default action for newly created history objects.
+     */
+    Pop = "POP",
+    /**
+     * A PUSH indicates a new entry being added to the history stack, such as when
+     * a link is clicked and a new page loads. When this happens, all subsequent
+     * entries in the stack are lost.
+     */
+    Push = "PUSH",
+    /**
+     * A REPLACE indicates the entry at the current index in the history stack
+     * being replaced by a new one.
+     */
+    Replace = "REPLACE"
+}
+/**
+ * The pathname, search, and hash values of a URL.
+ */
+export interface Path {
+    /**
+     * A URL pathname, beginning with a /.
+     */
+    pathname: string;
+    /**
+     * A URL search string, beginning with a ?.
+     */
+    search: string;
+    /**
+     * A URL fragment identifier, beginning with a #.
+     */
+    hash: string;
+}
+/**
+ * An entry in a history stack. A location contains information about the
+ * URL path, as well as possibly some arbitrary state and a key.
+ */
+export interface Location extends Path {
+    /**
+     * A value of arbitrary data associated with this location.
+     */
+    state: any;
+    /**
+     * A unique string associated with this location. May be used to safely store
+     * and retrieve data in some other storage API, like `localStorage`.
+     *
+     * Note: This value is always "default" on the initial location.
+     */
+    key: string;
+}
+/**
+ * A change to the current location.
+ */
+export interface Update {
+    /**
+     * The action that triggered the change.
+     */
+    action: Action;
+    /**
+     * The new location.
+     */
+    location: Location;
+}
+/**
+ * A function that receives notifications about location changes.
+ */
+export interface Listener {
+    (update: Update): void;
+}
+/**
+ * Describes a location that is the destination of some navigation, either via
+ * `history.push` or `history.replace`. May be either a URL or the pieces of a
+ * URL path.
+ */
+export declare type To = string | Partial<Path>;
+/**
+ * A history is an interface to the navigation stack. The history serves as the
+ * source of truth for the current location, as well as provides a set of
+ * methods that may be used to change it.
+ *
+ * It is similar to the DOM's `window.history` object, but with a smaller, more
+ * focused API.
+ */
+export interface History {
+    /**
+     * The last action that modified the current location. This will always be
+     * Action.Pop when a history instance is first created. This value is mutable.
+     */
+    readonly action: Action;
+    /**
+     * The current location. This value is mutable.
+     */
+    readonly location: Location;
+    /**
+     * Returns a valid href for the given `to` value that may be used as
+     * the value of an <a href> attribute.
+     *
+     * @param to - The destination URL
+     */
+    createHref(to: To): string;
+    /**
+     * Pushes a new location onto the history stack, increasing its length by one.
+     * If there were any entries in the stack after the current one, they are
+     * lost.
+     *
+     * @param to - The new URL
+     * @param state - Data to associate with the new location
+     */
+    push(to: To, state?: any): void;
+    /**
+     * Replaces the current location in the history stack with a new one.  The
+     * location that was replaced will no longer be available.
+     *
+     * @param to - The new URL
+     * @param state - Data to associate with the new location
+     */
+    replace(to: To, state?: any): void;
+    /**
+     * Navigates `n` entries backward/forward in the history stack relative to the
+     * current index. For example, a "back" navigation would use go(-1).
+     *
+     * @param delta - The delta in the stack index
+     */
+    go(delta: number): void;
+    /**
+     * Sets up a listener that will be called whenever the current location
+     * changes.
+     *
+     * @param listener - A function that will be called when the location changes
+     * @returns unlisten - A function that may be used to stop listening
+     */
+    listen(listener: Listener): () => void;
+}
+/**
+ * A user-supplied object that describes a location. Used when providing
+ * entries to `createMemoryHistory` via its `initialEntries` option.
+ */
+export declare type InitialEntry = string | Partial<Location>;
+export declare type MemoryHistoryOptions = {
+    initialEntries?: InitialEntry[];
+    initialIndex?: number;
+    v5Compat?: boolean;
+};
+/**
+ * A memory history stores locations in memory. This is useful in stateful
+ * environments where there is no web browser, such as node tests or React
+ * Native.
+ */
+export interface MemoryHistory extends History {
+    /**
+     * The current index in the history stack.
+     */
+    readonly index: number;
+}
+/**
+ * Memory history stores the current location in memory. It is designed for use
+ * in stateful non-browser environments like tests and React Native.
+ */
+export declare function createMemoryHistory(options?: MemoryHistoryOptions): MemoryHistory;
+/**
+ * A browser history stores the current location in regular URLs in a web
+ * browser environment. This is the standard for most web apps and provides the
+ * cleanest URLs the browser's address bar.
+ *
+ * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#browserhistory
+ */
+export interface BrowserHistory extends UrlHistory {
+}
+export declare type BrowserHistoryOptions = UrlHistoryOptions;
+/**
+ * Browser history stores the location in regular URLs. This is the standard for
+ * most web apps, but it requires some configuration on the server to ensure you
+ * serve the same app at multiple URLs.
+ *
+ * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createbrowserhistory
+ */
+export declare function createBrowserHistory(options?: BrowserHistoryOptions): BrowserHistory;
+/**
+ * A hash history stores the current location in the fragment identifier portion
+ * of the URL in a web browser environment.
+ *
+ * This is ideal for apps that do not control the server for some reason
+ * (because the fragment identifier is never sent to the server), including some
+ * shared hosting environments that do not provide fine-grained controls over
+ * which pages are served at which URLs.
+ *
+ * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#hashhistory
+ */
+export interface HashHistory extends UrlHistory {
+}
+export declare type HashHistoryOptions = UrlHistoryOptions;
+/**
+ * Hash history stores the location in window.location.hash. This makes it ideal
+ * for situations where you don't want to send the location to the server for
+ * some reason, either because you do cannot configure it or the URL space is
+ * reserved for something else.
+ *
+ * @see https://github.com/remix-run/history/tree/main/docs/api-reference.md#createhashhistory
+ */
+export declare function createHashHistory(options?: HashHistoryOptions): HashHistory;
+/**
+ * Creates a Location object with a unique key from the given Path
+ */
+export declare function createLocation(current: string | Location, to: To, state?: any, key?: string): Location;
+/**
+ * Creates a string URL path from the given pathname, search, and hash components.
+ */
+export declare function createPath({ pathname, search, hash, }: Partial<Path>): string;
+/**
+ * Parses a string URL path into its separate pathname, search, and hash components.
+ */
+export declare function parsePath(path: string): Partial<Path>;
+export interface UrlHistory extends History {
+}
+export declare type UrlHistoryOptions = {
+    window?: Window;
+    v5Compat?: boolean;
+};

package/index.d.ts

@@ -0,0 +1,11 @@
+import type { BrowserHistoryOptions, HashHistoryOptions, MemoryHistoryOptions } from "./history";
+import type { Router, RouterInit } from "./router";
+declare function createMemoryRouter({ initialEntries, initialIndex, ...routerInit }: MemoryHistoryOptions & Omit<RouterInit, "history">): Router;
+declare function createBrowserRouter({ window, ...routerInit }: BrowserHistoryOptions & Omit<RouterInit, "history">): Router;
+declare function createHashRouter({ window, ...routerInit }: HashHistoryOptions & Omit<RouterInit, "history">): Router;
+export * from "./router";
+export type { ActionFunction, DataRouteObject, FormEncType, FormMethod, JsonFunction, LoaderFunction, ParamParseKey, Params, PathMatch, PathPattern, RedirectFunction, RouteMatch, RouteObject, ShouldRevalidateFunction, Submission, } from "./utils";
+export { generatePath, getToPathname, invariant, isRouteErrorResponse, joinPaths, json, matchPath, matchRoutes, normalizePathname, redirect, resolvePath, resolveTo, stripBasename, warning, } from "./utils";
+export type { BrowserHistory, HashHistory, History, InitialEntry, Location, MemoryHistory, Path, To, } from "./history";
+export { Action, createBrowserHistory, createPath, createHashHistory, createMemoryHistory, parsePath, } from "./history";
+export { createBrowserRouter, createHashRouter, createMemoryRouter };