@passflow/react 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to `@passflow/react` are documented in this file.
 
+## [0.18.0] - 2026-11-03
+
+### Added
+
+- Email verification code step. When an app's registration policy requires a verified email, `/auth/register` and `/auth/login` may answer with a challenge instead of tokens. Sign-up and sign-in then show a code screen bound to that challenge. The submitted code goes to `/auth/validate`, and its answer continues the flow as before: second factor, PKCE or redirect. Resend repeats the original request. Cancel goes back to the form.
+- When the server's code budget is spent and it emails a link instead, the flow shows a "check your email" screen with no code input. The link opens the reset-password screen with a continuation grant. That screen titles itself "Create your password" and signs the user in with the tokens `/auth/password/change` returns.
+- `useEmailCodeStep()` (with `UseEmailCodeStep` and `UseEmailCodeStepOptions` types) drives the code step for custom UIs. Also exported: `EmailCodeStep`, `EmailVerificationStep`, `readEmailVerificationStep`, `emailCodeStepReducer`, `initialEmailCodeStepState`, and the error helpers `authErrorFrom`, `authRedirectErrorFrom`, `invitationJoinErrorFrom`, `emailCodeErrorMessage`, `newPasswordErrorMessage`, `serverMessageFor` and `isPasswordSavedRateLimit`.
+- `LoginScreen` states `email-code` and `new-password`, and an `info` tone for the `status` state, each with a Storybook story.
+- `Button` honours `aria-disabled`: it looks disabled and ignores clicks but stays focusable, so focus is not lost while a resend cooldown runs.
+
+### Changed
+
+- Requires `@passflow/core` `^0.22.0`, which adds `verifyEmailCode` and the `EmailVerificationRequired` event.
+- For these error ids the forms show the server's localized `error.message` instead of fixed copy: `error.registration.email.domain_not_allowed`, `email.required`, `email.not_verified_by_provider`, `error.invite.email.domain_not_allowed`, `error.verification.code.rate_limited`, and wrong, expired or used codes. The same list applies to errors that arrive in the URL from a federated sign-in. Other ids keep the fixed copy.
+- The reset-password screen is built on `LoginScreen`. Its outer wrapper class is unchanged, but the elements inside it are different, so `custom_css` rules aimed at its inner classes need updating.
+
+### Fixed
+
+- A 429 from the server is recognised whether core passes it on as a `PassflowError` or as a raw HTTP error, so rate limits show the rate-limit message instead of a generic failure.
+- A URL error message containing a literal `%` no longer breaks decoding.
+
+## [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

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:
 
@@ -947,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 |