use-go-back 1.0.0 → 1.1.0

package/dist/index-BbEcjnjB.d.ts

@@ -0,0 +1,46 @@
+//#region src/index.d.ts
+type PathnameMatcher = string | ((url: URL) => boolean);
+interface UseGoBackOptions {
+  /**
+   * The target pathname to go back to. Can be:
+   * - A string: exact pathname match (e.g., "/")
+   * - A function: custom matcher function that receives the full URL object (e.g., (url) => url.pathname === "/" || url.pathname.startsWith("/search") || url.searchParams.has("filter"))
+   * @default "/"
+   */
+  targetPathname?: PathnameMatcher;
+  /**
+   * Fallback URL to navigate to if Navigation API is not available and no matching history entry is found
+   */
+  fallbackUrl?: string;
+}
+/**
+ * Hook that provides a function to navigate back to a specific route in browser history.
+ * Uses the Navigation API to find the closest matching history entry and navigates back to it,
+ * which automatically restores scroll position.
+ *
+ * @param options - Configuration options
+ * @returns A function that navigates back to the target route
+ *
+ * @example
+ * ```tsx
+ * // Go back to the index page
+ * const goBack = useGoBack({ targetPathname: "/" });
+ *
+ * // Go back to any search-related page
+ * const goBack = useGoBack({
+ *   targetPathname: (url) => url.pathname.startsWith("/search")
+ * });
+ *
+ * // Match based on search params or origin
+ * const goBack = useGoBack({
+ *   targetPathname: (url) => url.origin === "https://app.example.com" || url.searchParams.has("filter")
+ * });
+ *
+ * // Use with a button
+ * <Button onClick={goBack}>Back</Button>
+ * ```
+ */
+declare function useGoBack(options?: UseGoBackOptions): () => void;
+//#endregion
+export { useGoBack };
+//# sourceMappingURL=index-BbEcjnjB.d.ts.map

package/dist/index.js

@@ -16,7 +16,12 @@ import { useCallback } from "react";
 *
 * // Go back to any search-related page
 * const goBack = useGoBack({
-*   targetPathname: (pathname) => pathname.startsWith("/search")
+*   targetPathname: (url) => url.pathname.startsWith("/search")
+* });
+*
+* // Match based on search params or origin
+* const goBack = useGoBack({
+*   targetPathname: (url) => url.origin === "https://app.example.com" || url.searchParams.has("filter")
 * });
 *
 * // Use with a button
@@ -25,9 +30,9 @@ import { useCallback } from "react";
 */
 function useGoBack(options = {}) {
 	const { targetPathname = "/", fallbackUrl } = options;
-	const matchesPathname = useCallback((pathname) => {
-		if (typeof targetPathname === "string") return pathname === targetPathname;
-		return targetPathname(pathname);
+	const matchesUrl = useCallback((url) => {
+		if (typeof targetPathname === "string") return url.pathname === targetPathname;
+		return targetPathname(url);
 	}, [targetPathname]);
 	return useCallback(() => {
 		const nav = window.navigation;
@@ -37,7 +42,7 @@ function useGoBack(options = {}) {
 			for (let i = currentIndex - 1; i >= 0; i--) {
 				const entry = entries[i];
 				if (entry) {
-					if (matchesPathname(new URL(entry.url).pathname)) {
+					if (matchesUrl(new URL(entry.url))) {
 						const stepsBack = currentIndex - i;
 						window.history.go(-stepsBack);
 						return;
@@ -49,7 +54,7 @@ function useGoBack(options = {}) {
 		if (finalFallback) window.location.href = finalFallback;
 		else window.history.back();
 	}, [
-		matchesPathname,
+		matchesUrl,
 		fallbackUrl,
 		targetPathname
 	]);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { useCallback } from \"react\"\n\ntype PathnameMatcher = string | ((pathname: string) => boolean)\n\ninterface UseGoBackOptions {\n\t/**\n\t * The target pathname to go back to. Can be:\n\t * - A string: exact pathname match (e.g., \"/\")\n\t * - A function: custom matcher function (e.g., (pathname) => pathname === \"/\" || pathname.startsWith(\"/search\"))\n\t * @default \"/\"\n\t */\n\ttargetPathname?: PathnameMatcher\n\t/**\n\t * Fallback URL to navigate to if Navigation API is not available and no matching history entry is found\n\t */\n\tfallbackUrl?: string\n}\n\n/**\n * Hook that provides a function to navigate back to a specific route in browser history.\n * Uses the Navigation API to find the closest matching history entry and navigates back to it,\n * which automatically restores scroll position.\n *\n * @param options - Configuration options\n * @returns A function that navigates back to the target route\n *\n * @example\n * ```tsx\n * // Go back to the index page\n * const goBack = useGoBack({ targetPathname: \"/\" });\n *\n * // Go back to any search-related page\n * const goBack = useGoBack({\n *   targetPathname: (pathname) => pathname.startsWith(\"/search\")\n * });\n *\n * // Use with a button\n * <Button onClick={goBack}>Back</Button>\n * ```\n */\nexport function useGoBack(options: UseGoBackOptions = {}) {\n\tconst { targetPathname = \"/\", fallbackUrl } = options\n\n\tconst matchesPathname = useCallback(\n\t\t(pathname: string): boolean => {\n\t\t\tif (typeof targetPathname === \"string\") {\n\t\t\t\treturn pathname === targetPathname\n\t\t\t}\n\t\t\treturn targetPathname(pathname)\n\t\t},\n\t\t[targetPathname]\n\t)\n\n\tconst goBack = useCallback(() => {\n\t\t// Check if Navigation API is available\n\t\t// @ts-expect-error - Navigation API is not yet in all TypeScript definitions\n\t\tconst nav = window.navigation\n\t\tif (nav && typeof nav === \"object\" && \"currentEntry\" in nav) {\n\t\t\tconst currentIndex = nav.currentEntry?.index ?? -1\n\t\t\tconst entries = nav.entries()\n\n\t\t\t// Look backwards through history to find the closest matching entry\n\t\t\tfor (let i = currentIndex - 1; i >= 0; i--) {\n\t\t\t\tconst entry = entries[i]\n\t\t\t\tif (entry) {\n\t\t\t\t\tconst url = new URL(entry.url)\n\t\t\t\t\t// Check if this entry matches the target pathname\n\t\t\t\t\tif (matchesPathname(url.pathname)) {\n\t\t\t\t\t\t// Calculate how many steps back we need to go\n\t\t\t\t\t\tconst stepsBack = currentIndex - i\n\t\t\t\t\t\t// Use browser navigation to go back, which restores scroll position\n\t\t\t\t\t\twindow.history.go(-stepsBack)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Fallback: if Navigation API is not available or no matching entry found\n\t\t// Use fallbackUrl if provided, otherwise use targetPathname if it's a string, otherwise use history.back()\n\t\tconst finalFallback = fallbackUrl ?? (typeof targetPathname === \"string\" ? targetPathname : undefined)\n\t\tif (finalFallback) {\n\t\t\twindow.location.href = finalFallback\n\t\t} else {\n\t\t\twindow.history.back()\n\t\t}\n\t}, [matchesPathname, fallbackUrl, targetPathname])\n\n\treturn goBack\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAgB,UAAU,UAA4B,EAAE,EAAE;CACzD,MAAM,EAAE,iBAAiB,KAAK,gBAAgB;CAE9C,MAAM,kBAAkB,aACtB,aAA8B;AAC9B,MAAI,OAAO,mBAAmB,SAC7B,QAAO,aAAa;AAErB,SAAO,eAAe,SAAS;IAEhC,CAAC,eAAe,CAChB;AAqCD,QAnCe,kBAAkB;EAGhC,MAAM,MAAM,OAAO;AACnB,MAAI,OAAO,OAAO,QAAQ,YAAY,kBAAkB,KAAK;GAC5D,MAAM,eAAe,IAAI,cAAc,SAAS;GAChD,MAAM,UAAU,IAAI,SAAS;AAG7B,QAAK,IAAI,IAAI,eAAe,GAAG,KAAK,GAAG,KAAK;IAC3C,MAAM,QAAQ,QAAQ;AACtB,QAAI,OAGH;SAAI,gBAFQ,IAAI,IAAI,MAAM,IAAI,CAEN,SAAS,EAAE;MAElC,MAAM,YAAY,eAAe;AAEjC,aAAO,QAAQ,GAAG,CAAC,UAAU;AAC7B;;;;;EAQJ,MAAM,gBAAgB,gBAAgB,OAAO,mBAAmB,WAAW,iBAAiB;AAC5F,MAAI,cACH,QAAO,SAAS,OAAO;MAEvB,QAAO,QAAQ,MAAM;IAEpB;EAAC;EAAiB;EAAa;EAAe,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { useCallback } from \"react\"\n\ntype PathnameMatcher = string | ((url: URL) => boolean)\n\ninterface UseGoBackOptions {\n\t/**\n\t * The target pathname to go back to. Can be:\n\t * - A string: exact pathname match (e.g., \"/\")\n\t * - A function: custom matcher function that receives the full URL object (e.g., (url) => url.pathname === \"/\" || url.pathname.startsWith(\"/search\") || url.searchParams.has(\"filter\"))\n\t * @default \"/\"\n\t */\n\ttargetPathname?: PathnameMatcher\n\t/**\n\t * Fallback URL to navigate to if Navigation API is not available and no matching history entry is found\n\t */\n\tfallbackUrl?: string\n}\n\n/**\n * Hook that provides a function to navigate back to a specific route in browser history.\n * Uses the Navigation API to find the closest matching history entry and navigates back to it,\n * which automatically restores scroll position.\n *\n * @param options - Configuration options\n * @returns A function that navigates back to the target route\n *\n * @example\n * ```tsx\n * // Go back to the index page\n * const goBack = useGoBack({ targetPathname: \"/\" });\n *\n * // Go back to any search-related page\n * const goBack = useGoBack({\n *   targetPathname: (url) => url.pathname.startsWith(\"/search\")\n * });\n *\n * // Match based on search params or origin\n * const goBack = useGoBack({\n *   targetPathname: (url) => url.origin === \"https://app.example.com\" || url.searchParams.has(\"filter\")\n * });\n *\n * // Use with a button\n * <Button onClick={goBack}>Back</Button>\n * ```\n */\nexport function useGoBack(options: UseGoBackOptions = {}) {\n\tconst { targetPathname = \"/\", fallbackUrl } = options\n\n\tconst matchesUrl = useCallback(\n\t\t(url: URL): boolean => {\n\t\t\tif (typeof targetPathname === \"string\") {\n\t\t\t\treturn url.pathname === targetPathname\n\t\t\t}\n\t\t\treturn targetPathname(url)\n\t\t},\n\t\t[targetPathname]\n\t)\n\n\tconst goBack = useCallback(() => {\n\t\t// Check if Navigation API is available\n\t\t// @ts-expect-error - Navigation API is not yet in all TypeScript definitions\n\t\tconst nav = window.navigation\n\t\tif (nav && typeof nav === \"object\" && \"currentEntry\" in nav) {\n\t\t\tconst currentIndex = nav.currentEntry?.index ?? -1\n\t\t\tconst entries = nav.entries()\n\n\t\t\t// Look backwards through history to find the closest matching entry\n\t\t\tfor (let i = currentIndex - 1; i >= 0; i--) {\n\t\t\t\tconst entry = entries[i]\n\t\t\t\tif (entry) {\n\t\t\t\t\tconst url = new URL(entry.url)\n\t\t\t\t\t// Check if this entry matches the target pathname\n\t\t\t\t\tif (matchesUrl(url)) {\n\t\t\t\t\t\t// Calculate how many steps back we need to go\n\t\t\t\t\t\tconst stepsBack = currentIndex - i\n\t\t\t\t\t\t// Use browser navigation to go back, which restores scroll position\n\t\t\t\t\t\twindow.history.go(-stepsBack)\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Fallback: if Navigation API is not available or no matching entry found\n\t\t// Use fallbackUrl if provided, otherwise use targetPathname if it's a string, otherwise use history.back()\n\t\tconst finalFallback = fallbackUrl ?? (typeof targetPathname === \"string\" ? targetPathname : undefined)\n\t\tif (finalFallback) {\n\t\t\twindow.location.href = finalFallback\n\t\t} else {\n\t\t\twindow.history.back()\n\t\t}\n\t}, [matchesUrl, fallbackUrl, targetPathname])\n\n\treturn goBack\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,UAAU,UAA4B,EAAE,EAAE;CACzD,MAAM,EAAE,iBAAiB,KAAK,gBAAgB;CAE9C,MAAM,aAAa,aACjB,QAAsB;AACtB,MAAI,OAAO,mBAAmB,SAC7B,QAAO,IAAI,aAAa;AAEzB,SAAO,eAAe,IAAI;IAE3B,CAAC,eAAe,CAChB;AAqCD,QAnCe,kBAAkB;EAGhC,MAAM,MAAM,OAAO;AACnB,MAAI,OAAO,OAAO,QAAQ,YAAY,kBAAkB,KAAK;GAC5D,MAAM,eAAe,IAAI,cAAc,SAAS;GAChD,MAAM,UAAU,IAAI,SAAS;AAG7B,QAAK,IAAI,IAAI,eAAe,GAAG,KAAK,GAAG,KAAK;IAC3C,MAAM,QAAQ,QAAQ;AACtB,QAAI,OAGH;SAAI,WAFQ,IAAI,IAAI,MAAM,IAAI,CAEX,EAAE;MAEpB,MAAM,YAAY,eAAe;AAEjC,aAAO,QAAQ,GAAG,CAAC,UAAU;AAC7B;;;;;EAQJ,MAAM,gBAAgB,gBAAgB,OAAO,mBAAmB,WAAW,iBAAiB;AAC5F,MAAI,cACH,QAAO,SAAS,OAAO;MAEvB,QAAO,QAAQ,MAAM;IAEpB;EAAC;EAAY;EAAa;EAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-go-back",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A React hook that navigates back to a specific route in browser history using the Navigation API, preserving scroll position",
   "type": "module",
   "main": "./dist/index.js",