use-go-back 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Forge 42
+
+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,98 @@
+# use-go-back
+
+A React hook that navigates back to a specific route in browser history using the Navigation API, preserving scroll position.
+
+## Features
+
+- 🎯 Navigate back to a specific pathname in history
+- 📜 Preserves scroll position automatically (thanks to Navigation API)
+- 🔍 Flexible pathname matching (exact string or custom function)
+- 🔄 Graceful fallback when Navigation API is not available
+- 📦 Zero dependencies (only React as peer dependency)
+- 🎨 TypeScript support
+
+## Installation
+
+```bash
+npm install use-go-back
+# or
+pnpm add use-go-back
+# or
+yarn add use-go-back
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { useGoBack } from "use-go-back";
+
+function MyComponent() {
+  const goBack = useGoBack({ targetPathname: "/" });
+
+  return <button onClick={goBack}>Go to Home</button>;
+}
+```
+
+### With Custom Pathname Matcher
+
+```tsx
+import { useGoBack } from "use-go-back";
+
+function SearchLayout() {
+  // Go back to any search-related page
+  const goBack = useGoBack({
+    targetPathname: (pathname) => pathname.startsWith("/search"),
+  });
+
+  return <button onClick={goBack}>Back to Search</button>;
+}
+```
+
+### With Fallback URL
+
+```tsx
+import { useGoBack } from "use-go-back";
+
+function MyComponent() {
+  const goBack = useGoBack({
+    targetPathname: "/dashboard",
+    fallbackUrl: "/dashboard", // Used if Navigation API is unavailable
+  });
+
+  return <button onClick={goBack}>Back to Dashboard</button>;
+}
+```
+
+## API
+
+### `useGoBack(options?)`
+
+Returns a function that navigates back to the target route.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `targetPathname` | `string \| ((pathname: string) => boolean)` | `"/"` | The target pathname to go back to. Can be an exact string match or a custom matcher function. |
+| `fallbackUrl` | `string` | `undefined` | Fallback URL to navigate to if Navigation API is not available and no matching history entry is found. |
+
+#### Returns
+
+A function `() => void` that navigates back to the target route when called.
+
+## How It Works
+
+1. **Navigation API**: The hook uses the [Navigation API](https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API) to access browser history entries.
+2. **History Search**: It searches backwards through history to find the closest entry matching your target pathname.
+3. **Scroll Preservation**: When using `window.history.go()`, the browser automatically restores the scroll position, which is perfect for nested routes.
+4. **Fallback**: If the Navigation API is not available or no matching entry is found, it falls back to the provided `fallbackUrl` or uses `history.back()`.
+
+## Browser Support
+
+The hook works in all modern browsers. For browsers that don't support the Navigation API, it gracefully falls back to using `window.location.href` or `history.back()`.
+
+## License
+
+MIT

package/dist/index-BDs7GAQ6.d.ts

@@ -0,0 +1,41 @@
+//#region src/index.d.ts
+type PathnameMatcher = string | ((pathname: string) => boolean);
+interface UseGoBackOptions {
+  /**
+   * The target pathname to go back to. Can be:
+   * - A string: exact pathname match (e.g., "/")
+   * - A function: custom matcher function (e.g., (pathname) => pathname === "/" || pathname.startsWith("/search"))
+   * @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: (pathname) => pathname.startsWith("/search")
+ * });
+ *
+ * // Use with a button
+ * <Button onClick={goBack}>Back</Button>
+ * ```
+ */
+declare function useGoBack(options?: UseGoBackOptions): () => void;
+//#endregion
+export { useGoBack };
+//# sourceMappingURL=index-BDs7GAQ6.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+//#region src/index.d.ts
+type PathnameMatcher = string | ((pathname: string) => boolean);
+interface UseGoBackOptions {
+  /**
+   * The target pathname to go back to. Can be:
+   * - A string: exact pathname match (e.g., "/")
+   * - A function: custom matcher function (e.g., (pathname) => pathname === "/" || pathname.startsWith("/search"))
+   * @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: (pathname) => pathname.startsWith("/search")
+ * });
+ *
+ * // Use with a button
+ * <Button onClick={goBack}>Back</Button>
+ * ```
+ */
+declare function useGoBack(options?: UseGoBackOptions): () => void;
+//#endregion
+export { useGoBack };
+//# sourceMappingURL=index-BDs7GAQ6.d.ts.map

package/dist/index.js

@@ -0,0 +1,60 @@
+import { useCallback } from "react";
+
+//#region src/index.ts
+/**
+* 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: (pathname) => pathname.startsWith("/search")
+* });
+*
+* // Use with a button
+* <Button onClick={goBack}>Back</Button>
+* ```
+*/
+function useGoBack(options = {}) {
+	const { targetPathname = "/", fallbackUrl } = options;
+	const matchesPathname = useCallback((pathname) => {
+		if (typeof targetPathname === "string") return pathname === targetPathname;
+		return targetPathname(pathname);
+	}, [targetPathname]);
+	return useCallback(() => {
+		const nav = window.navigation;
+		if (nav && typeof nav === "object" && "currentEntry" in nav) {
+			const currentIndex = nav.currentEntry?.index ?? -1;
+			const entries = nav.entries();
+			for (let i = currentIndex - 1; i >= 0; i--) {
+				const entry = entries[i];
+				if (entry) {
+					if (matchesPathname(new URL(entry.url).pathname)) {
+						const stepsBack = currentIndex - i;
+						window.history.go(-stepsBack);
+						return;
+					}
+				}
+			}
+		}
+		const finalFallback = fallbackUrl ?? (typeof targetPathname === "string" ? targetPathname : void 0);
+		if (finalFallback) window.location.href = finalFallback;
+		else window.history.back();
+	}, [
+		matchesPathname,
+		fallbackUrl,
+		targetPathname
+	]);
+}
+
+//#endregion
+export { useGoBack };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "use-go-back",
+  "version": "1.0.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",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gijsroge/use-go-back.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gijsroge/use-go-back/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "homepage": "https://github.com/gijsroge/use-go-back#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.17.4",
+    "@changesets/cli": "^2.29.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "22.14.1",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "@vitest/coverage-v8": "^3.1.1",
+    "happy-dom": "^17.4.4",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "tsdown": "^0.15.6",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts && pnpm run build:fix-types",
+    "build:fix-types": "node -e \"const fs=require('fs');const files=fs.readdirSync('dist');const dts=files.find(f=>f.endsWith('.d.ts')&&f.startsWith('index-'));if(dts)fs.copyFileSync('dist/'+dts,'dist/index.d.ts');\"",
+    "test:unit": "vitest run --passWithNoTests",
+    "test:cov": "vitest run --coverage",
+    "test:types": "tsc",
+    "test:publint": "publint --strict",
+    "test:exports": "attw --pack ."
+  }
+}