ui5-lib-guard-router 0.0.0 → 1.0.0

package/README.md

@@ -1,50 +1,278 @@
-# ui5.guard.router (Library)
+# ui5-lib-guard-router
 
-The core library providing `ui5.guard.router.Router` -- an extension of `sap.m.routing.Router` with async navigation guards.
+Drop-in replacement for `sap.m.routing.Router` that intercepts navigation **before** route matching, target loading, or view creation — preventing flashes of unauthorized content and polluted browser history.
 
-## Structure
+> Born from [SAP/openui5#3411](https://github.com/SAP/openui5/issues/3411), an open request since 2021 for native navigation guard support in UI5.
 
+> [!WARNING]
+> This library is **experimental**. The API may change without notice. Pin your version and review changes before upgrading.
+
+## Why
+
+UI5's router has no way to block or redirect navigation before views render. The usual workaround — scattering guard logic across `attachPatternMatched` callbacks — causes flashes of unauthorized content, polluted browser history, and duplicated checks across controllers.
+
+This library solves all three by intercepting at the router level, before any route matching begins.
+
+## Install
+
+```bash
+npm install ui5-lib-guard-router
 ```
-src/
-  Router.ts       Router implementation (overrides parse())
-  types.ts        TypeScript types (GuardFn, LeaveGuardFn, GuardContext, GuardResult, GuardRedirect, RouteGuardConfig, GuardRouter)
-  library.ts      UI5 library registration
-  manifest.json   Library manifest
-  .library        XML library descriptor
-  themes/         Theme placeholder (noLibraryCSS)
-test/
-  qunit/          QUnit unit tests (Router.qunit.ts, NativeRouterCompat.qunit.ts)
-  wdio-qunit.conf.ts   wdio config for running QUnit tests via wdio-qunit-service
+
+## Setup
+
+**1. Add the library dependency and set the router class in your `manifest.json`:**
+
+```json
+{
+	"sap.ui5": {
+		"dependencies": {
+			"libs": {
+				"ui5.guard.router": {}
+			}
+		},
+		"routing": {
+			"config": {
+				"routerClass": "ui5.guard.router.Router"
+			}
+		}
+	}
+}
 ```
 
-## Scripts
+All existing routes, targets, and navigation calls continue to work unchanged.
 
-```bash
-# Serve the library (for running QUnit tests in browser)
-npm start
-# => http://localhost:8080/test-resources/ui5/guard/router/qunit/testsuite.qunit.html
+**2. Register guards in your Component:**
+
+```typescript
+import UIComponent from "sap/ui/core/UIComponent";
+import type { GuardRouter } from "ui5/guard/router/types";
+
+export default class Component extends UIComponent {
+	static metadata = {
+		manifest: "json",
+		interfaces: ["sap.ui.core.IAsyncContentCreation"],
+	};
+
+	init(): void {
+		super.init();
+		const router = this.getRouter() as unknown as GuardRouter;
 
-# Build
-npm run build
+		// Route-specific guard — redirect when not logged in
+		router.addRouteGuard("protected", (context) => {
+			return isLoggedIn() ? true : "home";
+		});
 
-# Type check
-npm run typecheck
+		// Global guard — runs for every navigation
+		router.addGuard((context) => {
+			if (context.toRoute === "admin" && !isAdmin()) {
+				return "home";
+			}
+			return true;
+		});
+
+		router.initialize();
+	}
+}
 ```
 
-## Running QUnit tests
+## How it works
 
-From the monorepo root:
+The library extends `sap.m.routing.Router` and overrides `parse()`, the single method through which all navigation flows (programmatic `navTo`, browser back/forward, direct URL changes). Guards run before any route matching, target loading, or view creation.
 
-```bash
-npm run test:qunit
+The guard pipeline stays **synchronous when all guards return plain values** and only becomes async when a guard returns a Promise. A generation counter discards stale async results when navigations overlap, and an `AbortSignal` is passed to each guard so async work (like `fetch`) can be cancelled early.
+
+## API
+
+All methods return `this` for chaining.
+
+### Guard registration
+
+| Method                                                     | Description                                    |
+| ---------------------------------------------------------- | ---------------------------------------------- |
+| `addGuard(fn)`                                             | Global enter guard (runs for every navigation) |
+| `addRouteGuard(routeName, fn)`                             | Enter guard for a specific route               |
+| `addRouteGuard(routeName, { beforeEnter?, beforeLeave? })` | Enter and/or leave guards via object form      |
+| `addLeaveGuard(routeName, fn)`                             | Leave guard (runs when leaving the route)      |
+
+### Guard removal
+
+| Method                                                        | Description                                      |
+| ------------------------------------------------------------- | ------------------------------------------------ |
+| `removeGuard(fn)`                                             | Remove a global enter guard                      |
+| `removeRouteGuard(routeName, fn)`                             | Remove an enter guard                            |
+| `removeRouteGuard(routeName, { beforeEnter?, beforeLeave? })` | Remove enter and/or leave guards via object form |
+| `removeLeaveGuard(routeName, fn)`                             | Remove a leave guard                             |
+
+### GuardContext
+
+Every guard receives a `GuardContext` object:
+
+| Property      | Type                                               | Description                                         |
+| ------------- | -------------------------------------------------- | --------------------------------------------------- |
+| `toRoute`     | `string`                                           | Target route name (empty if no match)               |
+| `toHash`      | `string`                                           | Raw hash being navigated to                         |
+| `toArguments` | `Record<string, string \| Record<string, string>>` | Parsed route parameters                             |
+| `fromRoute`   | `string`                                           | Current route name (empty on first navigation)      |
+| `fromHash`    | `string`                                           | Current hash                                        |
+| `signal`      | `AbortSignal`                                      | Aborted when a newer navigation supersedes this one |
+
+### Return values
+
+**Enter guards** (`addGuard`, `addRouteGuard`):
+
+| Return                                         | Effect                                          |
+| ---------------------------------------------- | ----------------------------------------------- |
+| `true`                                         | Allow navigation                                |
+| `false`                                        | Block (stay on current route, no history entry) |
+| `"routeName"`                                  | Redirect to named route (replaces history)      |
+| `{ route, parameters?, componentTargetInfo? }` | Redirect with route parameters                  |
+| anything else (`null`, `undefined`)            | Treated as block                                |
+
+Only strict `true` allows navigation — no truthy coercion.
+
+**Leave guards** (`addLeaveGuard`):
+
+| Return                            | Effect                          |
+| --------------------------------- | ------------------------------- |
+| `true`                            | Allow leaving the current route |
+| `false` (or any non-`true` value) | Block                           |
+
+Leave guards cannot redirect. For redirection logic, use enter guards on the target route.
+
+### Execution order
+
+1. **Leave guards** for the current route (registration order)
+2. **Global enter guards** (registration order)
+3. **Route-specific enter guards** for the target (registration order)
+4. Pipeline **short-circuits** at the first non-`true` result
+
+## Examples
+
+### Async guard with AbortSignal
+
+```typescript
+router.addRouteGuard("dashboard", async (context) => {
+	const res = await fetch(`/api/access/${context.toRoute}`, {
+		signal: context.signal,
+	});
+	const { allowed } = await res.json();
+	return allowed ? true : "forbidden";
+});
+```
+
+### Redirect with parameters
+
+```typescript
+router.addGuard((context) => {
+	if (context.toRoute === "old-detail") {
+		return {
+			route: "detail",
+			parameters: { id: context.toArguments.id },
+		};
+	}
+	return true;
+});
+```
+
+### Guard factories
+
+```typescript
+// guards.ts
+import JSONModel from "sap/ui/model/json/JSONModel";
+import type { GuardFn, LeaveGuardFn, GuardContext, GuardResult } from "ui5/guard/router/types";
+
+export function createAuthGuard(authModel: JSONModel): GuardFn {
+	return (context: GuardContext): GuardResult => {
+		return authModel.getProperty("/isLoggedIn") ? true : "home";
+	};
+}
+
+export function createDirtyFormGuard(formModel: JSONModel): LeaveGuardFn {
+	return (context: GuardContext): boolean => {
+		return !formModel.getProperty("/isDirty");
+	};
+}
+```
+
+### Object form (enter + leave)
+
+```typescript
+router.addRouteGuard("editOrder", {
+	beforeEnter: createAuthGuard(authModel),
+	beforeLeave: createDirtyFormGuard(formModel),
+});
+```
+
+### Leave guard with controller lifecycle
+
+```typescript
+import type { GuardRouter, LeaveGuardFn } from "ui5/guard/router/types";
+import { createDirtyFormGuard } from "./guards";
+
+export default class EditOrderController extends Controller {
+	private _leaveGuard: LeaveGuardFn;
+
+	onInit(): void {
+		const formModel = new JSONModel({ isDirty: false });
+		this.getView()!.setModel(formModel, "form");
+
+		const router = (this.getOwnerComponent() as UIComponent).getRouter() as unknown as GuardRouter;
+		this._leaveGuard = createDirtyFormGuard(formModel);
+		router.addLeaveGuard("editOrder", this._leaveGuard);
+	}
+
+	onExit(): void {
+		const router = (this.getOwnerComponent() as UIComponent).getRouter() as unknown as GuardRouter;
+		router.removeLeaveGuard("editOrder", this._leaveGuard);
+	}
+}
+```
+
+> **User feedback on blocked navigation**: When a leave guard blocks, the router silently restores the previous hash. There is no built-in confirmation dialog. Show a `sap.m.MessageBox.confirm()` inside your leave guard (returning the user's choice as a `Promise<boolean>`) to make the block visible.
+
+> **Guard cleanup**: The router's `destroy()` method automatically clears all guards when the component is destroyed. Controller-registered guards persist across in-app navigations (since UI5 caches views), which is typically desired for route-specific guards tied to view state.
+
+## Limitations
+
+### Redirect targets bypass guards
+
+When a guard redirects from route A to route B, route B's guards are **not** evaluated. This prevents infinite redirect loops. In practice, redirect targets are typically "safe" routes (`home`, `login`) without guards. If you need guard logic on a redirect target, run the check inline:
+
+```typescript
+router.addRouteGuard("dashboard", (context) => {
+	if (!hasPermission()) {
+		return isOnboarded() ? "profile" : "onboarding";
+	}
+	return true;
+});
+```
+
+### URL bar flickers during async guards
+
+When a guard returns a Promise, the browser's URL bar shows the target hash while the guard resolves. If it blocks or redirects, the URL reverts. This is a UI5 architecture constraint — `HashChanger` updates the URL before `parse()` is called. Sync guards are not affected.
+
+Show a busy indicator while async guards resolve to communicate that navigation is in progress:
+
+```typescript
+router.addRouteGuard("dashboard", async (context) => {
+	app.setBusy(true);
+	try {
+		const res = await fetch(`/api/access/${context.toRoute}`, { signal: context.signal });
+		const { allowed } = await res.json();
+		return allowed ? true : "home";
+	} finally {
+		app.setBusy(false);
+	}
+});
 ```
 
-This uses `wdio-qunit-service` to launch the QUnit test suite in a headless Chrome browser and report results.
+## Compatibility
 
-To run tests interactively in a browser, start the library server (`npm start` in this directory) and open the testsuite URL above.
+- **Minimum UI5 version**: 1.118 (requires [`sap.ui.core.Lib`](https://sdk.openui5.org/api/sap.ui.core.Lib))
+- **Router APIs**: depends on [`getRouteInfoByHash`](https://sdk.openui5.org/api/sap.ui.core.routing.Router%23methods/getRouteInfoByHash) (since 1.75)
+- **Developed and tested against**: OpenUI5 1.144.0
 
-## Framework
+## License
 
-- OpenUI5 1.144.0
-- TypeScript via `ui5-tooling-transpile`
-- UI5 Tooling specVersion 4.0
+[MIT](https://github.com/wridgeu/ui5-lib-guard-router/blob/main/LICENSE)

package/dist/index.d.ts

@@ -22,6 +22,6 @@
 //   - @types/istanbul-lib-report@3.0.3
 //   - @types/istanbul-lib-coverage@2.0.6
 //   - @types/qunit@2.19.13
-/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>
 /// <reference path="./resources/ui5/guard/router/library.d.ts"/>
+/// <reference path="./resources/ui5/guard/router/Router.d.ts"/>
 /// <reference path="./resources/ui5/guard/router/types.d.ts"/>

package/dist/resources/ui5/guard/router/.library

@@ -1,17 +1,17 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<library xmlns="http://www.sap.com/sap.ui.library.xsd">
-	<name>ui5.guard.router</name>
-	<vendor>Marco</vendor>
-	<version>0.0.0</version>
-	<copyright></copyright>
-	<title>UI5 Router extension with async navigation guards</title>
-	<documentation>Extends sap.m.routing.Router with async navigation guards, running before route matching begins.</documentation>
-	<dependencies>
-		<dependency>
-			<libraryName>sap.ui.core</libraryName>
-		</dependency>
-		<dependency>
-			<libraryName>sap.m</libraryName>
-		</dependency>
-	</dependencies>
-</library>
+<?xml version="1.0" encoding="UTF-8" ?>
+<library xmlns="http://www.sap.com/sap.ui.library.xsd">
+	<name>ui5.guard.router</name>
+	<vendor>Marco</vendor>
+	<version>1.0.0</version>
+	<copyright></copyright>
+	<title>UI5 Router extension with async navigation guards</title>
+	<documentation>Extends sap.m.routing.Router with async navigation guards, running before route matching begins.</documentation>
+	<dependencies>
+		<dependency>
+			<libraryName>sap.ui.core</libraryName>
+		</dependency>
+		<dependency>
+			<libraryName>sap.m</libraryName>
+		</dependency>
+	</dependencies>
+</library>