@passflow/react 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to `@passflow/react` are documented in this file.
 
+## [0.17.0] - 2026-11-03
+
+### Changed
+
+- Requires `@passflow/core` `^0.21.0`: one token refresh per browser across tabs, with transient failures kept apart from the end of a session. See core's `docs/token-refresh.md`, "Migrating from 0.20.1". What reaches React apps: a network error or 5xx during refresh no longer signs the user out; `SessionExpired` fires only at a real end; `SignOut` fires once per sign-out.
+- `SessionExpiredReason` is core's type, re-exported from the package root as before. It adds `'successor_timeout'` and `'identity_changed'`, so `useSessionExpired` and `AuthProvider`'s `onSessionExpired` can receive them. An exhaustive `switch` over the reason needs the new cases.
+
+### Added
+
+- `useRefreshStatus()` returns `{ isFailing, since, nextRetryAt }` while token refresh is failing transiently (`RefreshFailing` until `RefreshRecovered`), for a "reconnecting" notice. Call it in a component that lives as long as the app: a component that mounts mid-episode starts idle.
+
+### Fixed
+
+- `PassflowProvider` disposes the `Passflow` instances it replaces (its state changes on app ID discovery and app settings) and the one it holds on unmount. From core 0.21 each instance holds refresh timers, a `BroadcastChannel` and Web Locks, so an undisposed one went on acting as another tab.
+
+## [0.16.0] - 2026-11-03
+
+### Breaking
+
+- `react-router` is no longer a peer dependency, and the package does not import it. The only peers are `react` and `react-dom`, `^18 || ^19`. `PassflowFlow` keeps its own small router, so it works the same in an app that routes with React Router, TanStack Router, Wouter, another router, or none. A host that installed `react-router` only for this package can remove it.
+- `PassflowFlow` no longer picks up a host React Router `<Router>`, and the console warning about `routerType` inside one is gone. Inside an app router in browser mode it shares the address bar with it: each side sees the other's navigations, and Back reaches both. Mount it on a catch-all route (`/auth/*` in React Router, `/auth/$` in TanStack Router, `<Route path="/auth" nest>` in Wouter).
+- `pathPrefix` is an absolute path from the root of the URL. When it is not given, the flow takes it from the first URL it sees, so `<PassflowFlow />` on `/auth` or `/auth/signin` uses `/auth`. Before, inside a host router, it was relative to the parent route.
+- `TwoFactorSetupMagicLinkFlow` no longer uses React Router's `useParams`. It reads the token from the URL segment after `/two-factor-setup-magic-link/`, or from a new `token` prop.
+
+### Added
+
+- `<PassflowFlow />` with no props works: browser history, prefix from the URL, every screen at a fixed path under it (`/signin`, `/signup`, `/verify-challenge-otp`, `/two-factor-setup-magic-link/:token`, …).
+- Full control: pass `location` and `navigate` together and the app's router owns the location, for example a TanStack Router memory history. Their types are exported as `PassflowFlowLocation` and `PassflowFlowNavigate`.
+- `PassflowFlow` serves the 2FA setup magic link (`/two-factor-setup-magic-link/:token`) as one of its screens.
+
+### Fixed
+
+- Forms inside `PassflowFlow` read search params from the flow's location. In memory or hash mode, or under `location` + `navigate`, they read the address bar, which never carried them; forgot-password then threw "Invalid default method param".
+
+### Internal
+
+- Tests run the zero-config flow inside React Router, TanStack Router and Wouter (jsdom), and inside a TanStack Router app in Chromium. `@tanstack/react-router` and `wouter` are dev dependencies; `react-router` stays one, for those tests and the docs.
+- The consumer type check installs no router.
+
 ## [0.15.1] - 2026-11-02
 
 ### Fixed

package/README.md

@@ -46,6 +46,8 @@ This is a SDK for react application.
     - [useJoinInvite](#usejoininvite)
     - [useLogout](#uselogout)
     - [usePasswordlessComplete](#usepasswordlesscomplete)
+    - [useSessionExpired](#usesessionexpired)
+    - [useRefreshStatus](#userefreshstatus)
 
 to install just type:
 
@@ -137,17 +139,15 @@ Both scripts automatically start the demo app and Storybook. `pnpm test` uses th
 ## Installation
 
 ```bash
-pnpm add @passflow/react react-router
+pnpm add @passflow/react
 ```
 
-`react-router` (`^7.0.0 || ^8.0.0`) is a required peer dependency and is not bundled, so install it even when the app routes with Wouter or TanStack Router. `react-router-dom` is not needed: from v7 on, `BrowserRouter` and the rest are exported by `react-router`.
+No router is needed. `PassflowFlow` has its own small router, and works on its own or inside an app routed by React Router, TanStack Router, Wouter or anything else.
 
 ## Requirements
 
-- React 18+ (React 19.2.7+ with React Router 8)
-- React Router 7 or 8 (React Router 6 is not supported)
+- React 18 or 19
 - Node `^22.12.0 || ^24.0.0 || >=26.0.0`
-- Your app may route with React Router, Wouter or TanStack Router
 
 ## Integration
 
@@ -246,21 +246,63 @@ authentication-context claims those tokens carry.
 
 ### PassflowFlow
 
+The whole sign-in experience on its own pages: sign-in, sign-up, one-time codes, magic links, password reset, invitations and two-factor. It needs no router and no setup:
+
+```tsx
+<PassflowProvider url="https://auth.example.com" appId="your-app-id">
+  <PassflowFlow />
+</PassflowProvider>
+```
+
 | Prop | Type | Description |
 |------|------|-------------|
 | successAuthRedirect | string | URL to redirect after successful authentication |
-| federatedDisplayMode | "popup" \| "redirect" | Federated authentication display mode |
-| pathPrefix | string | Prefix for all routes (optional) |
+| federatedDisplayMode | "modal" \| "redirect" | Federated authentication display mode |
+| pathPrefix | string | Where the flow lives, such as `/auth`. Optional: worked out from the first URL |
+| routerType | "browser" \| "hash" \| "memory" | The history the flow keeps. Default `browser` |
+| location, navigate | see below | Full control by the app's router. Optional, always together |
+
+**Paths.** The flow's screens are `<prefix>/signin`, `<prefix>/signup`, `<prefix>/verify-challenge-otp`, `<prefix>/verify-challenge-magic-link`, `<prefix>/forgot-password`, `<prefix>/forgot-password/success`, `<prefix>/password/reset`, `<prefix>/invitation`, `<prefix>/two-factor-verify`, `<prefix>/two-factor-setup` and `<prefix>/two-factor-setup-magic-link/:token`. Without `pathPrefix` the flow takes the prefix from the first URL it sees: `/auth/signin` and `/auth` both give `/auth`, `/` gives none. A path under the prefix that names no screen goes to sign-in.
 
-Inside an app that already has a React Router `<Router>`, `PassflowFlow` uses that router rather than its own (`routerType` is ignored). Mount it under a splat route so its own routes can match, and `pathPrefix` is relative to that route:
+**Inside an app's router.** Mount the flow on a catch-all route; nothing else is needed. The flow moves the address bar and announces it with `popstate`, the event React Router, TanStack Router and Wouter listen to, so the app's router follows the flow and the flow follows the app, Back and Forward included:
 
 ```tsx
-<Routes>
-  <Route path="/" element={<Home />} />
-  <Route path="/auth/*" element={<PassflowFlow successAuthRedirect="/" />} />
-</Routes>
+// TanStack Router
+const authRoute = createRoute({ getParentRoute: () => rootRoute, path: '/auth/$', component: () => <PassflowFlow /> });
+
+// React Router
+<Route path="/auth/*" element={<PassflowFlow />} />
+
+// Wouter
+<Route path="/auth" nest><PassflowFlow /></Route>
 ```
 
+**`routerType`.** `browser` (default) uses the address bar. `hash` keeps the flow's path after `#`. `memory` leaves the URL alone, for an embedded widget or tests.
+
+**Full control.** When the app's router does not use the address bar (it runs in hash or memory mode), hand the flow its location and a way to move it. `routerType` is then not used:
+
+```tsx
+// TanStack Router with a memory or hash history
+function AuthPage() {
+  const router = useRouter();
+  const location = useRouterState({ select: (state) => state.location });
+  return (
+    <PassflowFlow
+      location={{ pathname: location.pathname, search: location.searchStr }}
+      navigate={(to, { replace }) => {
+        const href = `${to.pathname}${to.search}`;
+        if (replace) router.history.replace(href);
+        else router.history.push(href);
+      }}
+    />
+  );
+}
+```
+
+`TwoFactorSetupMagicLinkFlow` can also be mounted on its own page. It reads the token from the URL (the segment after `/two-factor-setup-magic-link/`), or takes it as a `token` prop.
+
+The sections below wire the app's router into the **standalone form components** (`SignIn`, `SignUp`, …) through `PassflowProvider`'s `navigate` and `router` props. `PassflowFlow` does not need them.
+
 ### React Router
 
 Example of integration with React Router:
@@ -907,3 +949,43 @@ const { fetch, isLoading, isError, error } = usePasswordlessComplete();
 | isLoading | `boolean` | Loading state |
 | isError | `boolean` | Error state |
 | error | `string` | Error message |
+
+### useSessionExpired
+Hook for reacting to the end of a session, for example to redirect to your login page.
+
+```typescript
+const { isSessionExpired, expiredReason, resetSessionExpired } = useSessionExpired({
+  onSessionExpired: (reason) => navigate('/signin'),
+});
+```
+
+`SessionExpired` fires only when the session has really ended: the last auth strike (`'refresh_failed'`), no successor token pair in time (`'successor_timeout'`), or another user's tokens in storage (`'identity_changed'`). A transient refresh failure (network error, 5xx) keeps the session and shows up as `RefreshFailing` / `RefreshRecovered` instead; use [useRefreshStatus](#userefreshstatus) for that. The state resets on `SignIn` and `Register`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| onSessionExpired | `(reason: SessionExpiredReason) => void` (optional) | Called when the session ends |
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isSessionExpired | `boolean` | True once the session has ended |
+| expiredReason | `SessionExpiredReason \| null` | Why it ended (`SessionExpiredReason` is exported from `@passflow/core`) |
+| resetSessionExpired | `() => void` | Clears the expired state |
+
+### useRefreshStatus
+Hook for showing a "connection trouble" notice while token refresh is failing transiently. The session is kept during the episode; show the notice on `RefreshFailing` and hide it on `RefreshRecovered`.
+
+```typescript
+const { isFailing, since, nextRetryAt } = useRefreshStatus();
+```
+
+Set by `RefreshFailing`. Cleared by `RefreshRecovered`, `SessionExpired`, `SignOut`, `SignIn` and `Register`. The episode is known only from events, so a component that mounts after `RefreshFailing` starts idle: call the hook in a component that lives as long as the app, near `PassflowProvider`.
+
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| isFailing | `boolean` | True inside a transient-failure episode |
+| since | `number \| null` | Epoch ms of the episode's first failure |
+| nextRetryAt | `number \| null` | Epoch ms of the pending retry, when known |