react-router 7.15.1 → 8.3.0

package/dist/development/lib/href.d.ts

@@ -0,0 +1,36 @@
+
+import { Equal } from "./types/utils.js";
+import { Pages } from "./types/register.js";
+
+//#region lib/href.d.ts
+type Args = { [K in keyof Pages]: ToArgs<Pages[K]["params"]> };
+type ToArgs<Params extends Record<string, string | undefined>> = Equal<Params, {}> extends true ? [] : Partial<Params> extends Params ? [Params] | [] : [Params];
+/**
+ * Returns a resolved URL path for the specified route.
+ *
+ * Param values are percent-encoded for use in a path segment: characters that
+ * would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+ * are escaped, while characters that RFC 3986 allows literally in a path
+ * segment (`$ & + , ; = : @`) are kept as-is. Note this differs from query-string
+ * encoding (`encodeURIComponent`/`URLSearchParams`), where those characters are
+ * delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+ * preserving `/` separators.
+ *
+ * See [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
+ *
+ * @example
+ * const h = href("/:lang?/about", { lang: "en" })
+ * // -> `/en/about`
+ *
+ * <Link to={href("/products/:id", { id: "abc123" })} />
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @param path The route path to resolve
+ * @param args The route params to use when resolving the path
+ * @returns The resolved URL path
+ */
+declare function href<Path extends keyof Args>(path: Path, ...args: Args[Path]): string;
+//#endregion
+export { href };

package/dist/development/lib/href.js

@@ -0,0 +1,70 @@
+/**
+ * react-router v8.3.0
+ *
+ * Copyright (c) Remix Software Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE.md file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import { encodePathParam } from "./router/utils.js";
+//#region lib/href.ts
+function stringify(p) {
+	return p == null ? "" : typeof p === "string" ? p : String(p);
+}
+/**
+* Returns a resolved URL path for the specified route.
+*
+* Param values are percent-encoded for use in a path segment: characters that
+* would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+* are escaped, while characters that RFC 3986 allows literally in a path
+* segment (`$ & + , ; = : @`) are kept as-is. Note this differs from query-string
+* encoding (`encodeURIComponent`/`URLSearchParams`), where those characters are
+* delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+* preserving `/` separators.
+*
+* See [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
+*
+* @example
+* const h = href("/:lang?/about", { lang: "en" })
+* // -> `/en/about`
+*
+* <Link to={href("/products/:id", { id: "abc123" })} />
+*
+* @public
+* @category Utils
+* @mode framework
+* @param path The route path to resolve
+* @param args The route params to use when resolving the path
+* @returns The resolved URL path
+*/
+function href(path, ...args) {
+	let params = args[0];
+	let result = trimTrailingSplat(path).replace(/\/:([\w-]+)(\?)?/g, (_, param, questionMark) => {
+		const isRequired = questionMark === void 0;
+		const value = params?.[param];
+		if (isRequired && value === void 0) throw new Error(`Path '${path}' requires param '${param}' but it was not provided`);
+		return value == null ? "" : "/" + encodePathParam(stringify(value));
+	});
+	if (path.endsWith("*")) {
+		const value = params?.["*"];
+		if (value !== void 0) result += "/" + stringify(value).split("/").map(encodePathParam).join("/");
+	}
+	return result || "/";
+}
+/**
+* Removes a trailing splat and any number of slashes from the end of the path.
+*
+* Benchmarked to be faster than `path.replace(/\/*\*?$/, "")`, which backtracks.
+*/
+function trimTrailingSplat(path) {
+	let i = path.length - 1;
+	let char = path[i];
+	if (char !== "*" && char !== "/") return path;
+	i--;
+	for (; i >= 0; i--) if (path[i] !== "/") break;
+	return path.slice(0, i + 1);
+}
+//#endregion
+export { href };

package/dist/development/lib/router/history.d.ts

@@ -0,0 +1,264 @@
+
+//#region lib/router/history.d.ts
+/**
+ * Actions represent the type of change to a location value.
+ */
+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.
+ */
+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.
+ */
+interface Location<State = any> extends Path {
+  /**
+   * A value of arbitrary data associated with this location.
+   */
+  state: State;
+  /**
+   * 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;
+  /**
+   * The masked location displayed in the URL bar, which differs from the URL the
+   * router is operating on
+   */
+  mask?: Path;
+}
+/**
+ * A change to the current location.
+ */
+interface Update {
+  /**
+   * The action that triggered the change.
+   */
+  action: Action;
+  /**
+   * The new location.
+   */
+  location: Location;
+  /**
+   * The delta between this location and the former location in the history stack
+   */
+  delta: number | null;
+}
+/**
+ * A function that receives notifications about location changes.
+ */
+interface Listener {
+  (update: Update): void;
+}
+/**
+ * Describes a location that is the destination of some navigation used in
+ * {@link Link}, {@link useNavigate}, etc.
+ */
+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.
+ */
+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;
+  /**
+   * Returns a URL for the given `to` value
+   *
+   * @param to - The destination URL
+   */
+  createURL(to: To): URL;
+  /**
+   * Encode a location the same way window.history would do (no-op for memory
+   * history) so we ensure our PUSH/REPLACE navigations for data routers
+   * behave the same as POP
+   *
+   * @param to Unencoded path
+   */
+  encodeLocation(to: To): Path;
+  /**
+   * 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.
+ */
+type InitialEntry = string | Partial<Location>;
+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.
+ */
+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.
+ */
+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
+ */
+interface BrowserHistory extends UrlHistory {}
+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
+ */
+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
+ */
+interface HashHistory extends UrlHistory {}
+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
+ */
+declare function createHashHistory(options?: HashHistoryOptions): HashHistory;
+/**
+ * @private
+ */
+declare function invariant(value: boolean, message?: string): asserts value;
+declare function invariant<T>(value: T | null | undefined, message?: string): asserts value is T;
+/**
+ * Creates a string URL path from the given pathname, search, and hash components.
+ *
+ * @public
+ * @category Utils
+ * @param path The pathname, search, and hash components to combine.
+ * @returns The combined URL path.
+ */
+declare function createPath({
+  pathname,
+  search,
+  hash
+}: Partial<Path>): string;
+/**
+ * Parses a string URL path into its separate pathname, search, and hash components.
+ *
+ * @public
+ * @category Utils
+ * @param path The URL path to parse.
+ * @returns The parsed pathname, search, and hash components.
+ */
+declare function parsePath(path: string): Partial<Path>;
+interface UrlHistory extends History {}
+type UrlHistoryOptions = {
+  window?: Window;
+  v5Compat?: boolean;
+};
+//#endregion
+export { Action, History, InitialEntry, Location, Path, To, createBrowserHistory, createHashHistory, createMemoryHistory, createPath, invariant, parsePath };