@easygov/react-components 0.12.0 → 0.14.0

package/README.md

@@ -121,6 +121,27 @@ app. An absent permission never means "allowed".
 The header refetches the context whenever the URL's pathname changes, including client-side router
 navigations; a change of only the query string or fragment does not refetch.
 
+#### The context is renewed before it expires
+
+`contextJwt` is short-lived: core-backend signs it with an `exp` (5 minutes by default). Without a
+renewal, a page that stays on one URL would send an expired token to its backend. So the header
+fetches a new context about 60 seconds before `exp` and keeps doing so for as long as the user is
+signed in. Plan for these consequences:
+
+- **Forward `contextJwt` fresh.** Read it from the hook (or the latest event) when you make a
+  request; don't capture it once at mount.
+- **A renewal is not a change.** Each renewal delivers a new `contextJwt`, but when the context
+  itself is unchanged, `claims` is the **same object** as before. An effect or memo keyed on
+  `claims` therefore does not re-run, and a form you prefilled from it keeps what the user typed.
+  Read `claims` for what the context says, `contextJwt` for the token.
+- **Never reset user input from `onContextChange` or the `contextchange` event** without checking
+  whether the content changed (below). Both fire on every renewal, roughly every 4 minutes.
+- **A failed renewal is retried quietly** every 15 seconds while the old token is still valid.
+  Only if the token expires without a successful renewal, or core refuses the request for good
+  (for example `customer-account-not-accessible`), the header shows its error dialog, once per
+  outage. The previous `claims` stay in place meanwhile. A failed fetch after a navigation shows
+  the dialog at once and is then retried the same way; a refusal for good is not retried.
+
 `claims` is `null` until the first response lands and again after logout — render a fallback,
 don't assume it is present on first paint. The hook reflects the last context an `EasygovHeader`
 resolved; it never fetches on its own, and it is not cleared when the header unmounts. Claims
@@ -131,10 +152,22 @@ Outside React — including `<eg-easygov-header>` — listen for the event inste
 
 ```js
 document.addEventListener('contextchange', (e) => {
-  const { contextJwt, claims } = e.detail;
+  const { contextJwt, claims, contentChanged } = e.detail;
+  if (contentChanged) {
+    prefillForm(claims); // a real change: new account, process, ...
+  }
+  // Always keep the newest token for requests to your backend.
+  latestContextJwt = contextJwt;
 });
 ```
 
+`contentChanged` is `true` for the first context after sign-in and whenever `claims` differs from
+the previous event; it is `false` when the event only delivers a renewed token. Prefill only when
+it is `true`, otherwise every renewal overwrites what the user has typed since. In TypeScript the
+detail is typed as `HeaderContextChangeDetail`, exported by both `@easygov/react-components` and
+`@easygov/web-components`. The `onContextChange` callback has no such flag —
+compare `claims` by identity there (`claims !== previousClaims`).
+
 **The claims are decoded, not verified.** Use them for prefilling and rendering. Any backend
 that receives `contextJwt` must verify its signature against core-backend's published JWKS
 before trusting a claim.

package/dist/easygov.d.mts

@@ -453,6 +453,21 @@ interface HeaderContextClaims {
      */
     parentProcessId?: string;
 }
+/**
+ * `detail` of the `contextchange` CustomEvent. The event fires for every new JWT, which includes
+ * the background refresh that renews it shortly before it expires; `contentChanged` says whether
+ * `claims` differs from what the previous event delivered.
+ */
+interface HeaderContextChangeDetail {
+    contextJwt: string;
+    claims: HeaderContextClaims;
+    /**
+     * `true` for the first context of a session and whenever `claims` differs from the previous
+     * event's. `false` for a refresh that only renewed the token: prefilling a form from `claims`
+     * on such an event would overwrite what the user has typed since.
+     */
+    contentChanged: boolean;
+}
 
 interface EasygovHeaderContext {
     contextJwt: string | null;
@@ -598,6 +613,11 @@ declare function useEasygovAuthStatus(): AuthStatus;
  * still describe a previously selected account after the URL has moved on. Only sign-out (or a
  * failed *first* fetch) leaves `claims` at `null`.
  *
+ * `contextJwt` is renewed shortly before it expires (5 minutes by default), so it changes about
+ * every 4 minutes while the page stays put. `claims` keeps its identity across a renewal that
+ * changed nothing else, so an effect or memo keyed on `claims` does not re-run — read
+ * `contextJwt` when forwarding the token, `claims` when rendering or prefilling.
+ *
  * IMPORTANT — trust boundary: `claims` is decoded, NOT signature-verified. Use it to prefill
  * forms and drive rendering; never to authorize. A backend receiving `contextJwt` MUST verify it
  * against core-backend's published JWKS.
@@ -629,6 +649,14 @@ interface EasygovHeaderProps {
      * `header-context` endpoint (mirrored by the `contextchange` CustomEvent
      * dispatched on the header element), together with its decoded `claims`.
      *
+     * IMPORTANT — fires on every renewal, not only when the context changes. The JWT is short-lived
+     * (5 minutes by default), so the header fetches a new one shortly before it expires; that
+     * arrives here as a new `contextJwt`. When the refreshed context equals the previous one,
+     * `claims` is the very same object as in the previous call, so `claims !== previousClaims`
+     * tells a real change from a renewal. Never reset user input (a prefilled form) from this
+     * callback without that check. The `contextchange` event carries the same answer as
+     * `detail.contentChanged`.
+     *
      * Both are always present when this fires: a payload that fails to decode never produces a
      * `contextJwt`, so a decode failure suppresses the call rather than delivering null claims.
      *
@@ -688,4 +716,4 @@ declare function getEasygovDisplayLanguage(): Locale;
 declare function setEasygovDisplayLanguage(locale: Locale): void;
 declare function subscribeEasygovDisplayLanguage(listener: () => void): () => void;
 
-export { type AuthStatus, BrandBase, BrandEasygov, BrandFacebook, BrandKdk, BrandLinkedin, type BrandProps, BrandSeg, BrandSgv, BrandSsv, BrandSwiss, BrandXing, BrandYoutube, Button, type ButtonProps, type DesktopSpan, Dropdown, DropdownChip, DropdownChipsOverflow, type DropdownChipsOverflowProps, DropdownChipsTrigger, type DropdownChipsTriggerProps, DropdownCollection, DropdownEmpty, DropdownGroup, DropdownGroupLabel, DropdownHelperText, type DropdownHelperTextProps, DropdownInput, DropdownItem, type DropdownItemProps, DropdownItemText, DropdownLabel, type DropdownLabelProps, DropdownList, DropdownPopup, type DropdownPopupProps, DropdownSeparator, DropdownToggle, DropdownTrigger, type DropdownTriggerProps, DropdownValue, EasygovFooter, EasygovHeader, type EasygovHeaderContext, type EasygovHeaderProps, type EasygovSession, type EasygovVersionInfo, ErrorDialog, type ErrorDialogProps, Grid, GridItem, type GridItemProps, type GridProps, type AccountVerificationStatus as HeaderContextAccountVerificationStatus, type HeaderContextClaims, type IndividualAccount as HeaderContextIndividualAccount, type ManagementRole as HeaderContextManagementRole, type ManagementRoleStatus as HeaderContextManagementRoleStatus, type ManagementRoleType as HeaderContextManagementRoleType, type OrganizationAccount as HeaderContextOrganizationAccount, type PermissionLevel as HeaderContextPermissionLevel, type ProcessStatus as HeaderContextProcessStatus, type ServiceApp as HeaderContextServiceApp, type ServicePermission as HeaderContextServicePermission, type UserProfile as HeaderContextUserProfile, Heading, type HeadingProps, Input, type InputProps, type Locale, type MobileSpan, NavigationMenu, NavigationMenuAnchor, type NavigationMenuAnchorProps, NavigationMenuContent, type NavigationMenuContentProps, NavigationMenuItem, type NavigationMenuItemProps, NavigationMenuLink, type NavigationMenuLinkProps, NavigationMenuList, type NavigationMenuListProps, type NavigationMenuProps, NavigationMenuTrigger, type NavigationMenuTriggerProps, RequireCustomerAccount, type RequireCustomerAccountProps, RequireSession, type RequireSessionProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectGroupLabel, type SelectGroupLabelProps, SelectHelperText, type SelectHelperTextProps, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectSeparator, type SelectSeparatorProps, SelectTrigger, type SelectTriggerProps, type SelectedCustomerAccount, type SelectedProcess, type SessionUser, type TabletSpan, Text, TextLink, type TextLinkProps, type TextProps, buttonVariants, getAuthStatus, getEasygovDisplayLanguage, headingVariants, requireSession, setEasygovBusinessModuleVersion, setEasygovDisplayLanguage, subscribeEasygovDisplayLanguage, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovDisplayLanguage, useEasygovHeaderContext, useEasygovSession, useEasygovVersionInfo, useRequireCustomerAccount };
+export { type AuthStatus, BrandBase, BrandEasygov, BrandFacebook, BrandKdk, BrandLinkedin, type BrandProps, BrandSeg, BrandSgv, BrandSsv, BrandSwiss, BrandXing, BrandYoutube, Button, type ButtonProps, type DesktopSpan, Dropdown, DropdownChip, DropdownChipsOverflow, type DropdownChipsOverflowProps, DropdownChipsTrigger, type DropdownChipsTriggerProps, DropdownCollection, DropdownEmpty, DropdownGroup, DropdownGroupLabel, DropdownHelperText, type DropdownHelperTextProps, DropdownInput, DropdownItem, type DropdownItemProps, DropdownItemText, DropdownLabel, type DropdownLabelProps, DropdownList, DropdownPopup, type DropdownPopupProps, DropdownSeparator, DropdownToggle, DropdownTrigger, type DropdownTriggerProps, DropdownValue, EasygovFooter, EasygovHeader, type EasygovHeaderContext, type EasygovHeaderProps, type EasygovSession, type EasygovVersionInfo, ErrorDialog, type ErrorDialogProps, Grid, GridItem, type GridItemProps, type GridProps, type AccountVerificationStatus as HeaderContextAccountVerificationStatus, type HeaderContextChangeDetail, type HeaderContextClaims, type IndividualAccount as HeaderContextIndividualAccount, type ManagementRole as HeaderContextManagementRole, type ManagementRoleStatus as HeaderContextManagementRoleStatus, type ManagementRoleType as HeaderContextManagementRoleType, type OrganizationAccount as HeaderContextOrganizationAccount, type PermissionLevel as HeaderContextPermissionLevel, type ProcessStatus as HeaderContextProcessStatus, type ServiceApp as HeaderContextServiceApp, type ServicePermission as HeaderContextServicePermission, type UserProfile as HeaderContextUserProfile, Heading, type HeadingProps, Input, type InputProps, type Locale, type MobileSpan, NavigationMenu, NavigationMenuAnchor, type NavigationMenuAnchorProps, NavigationMenuContent, type NavigationMenuContentProps, NavigationMenuItem, type NavigationMenuItemProps, NavigationMenuLink, type NavigationMenuLinkProps, NavigationMenuList, type NavigationMenuListProps, type NavigationMenuProps, NavigationMenuTrigger, type NavigationMenuTriggerProps, RequireCustomerAccount, type RequireCustomerAccountProps, RequireSession, type RequireSessionProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectGroupLabel, type SelectGroupLabelProps, SelectHelperText, type SelectHelperTextProps, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectSeparator, type SelectSeparatorProps, SelectTrigger, type SelectTriggerProps, type SelectedCustomerAccount, type SelectedProcess, type SessionUser, type TabletSpan, Text, TextLink, type TextLinkProps, type TextProps, buttonVariants, getAuthStatus, getEasygovDisplayLanguage, headingVariants, requireSession, setEasygovBusinessModuleVersion, setEasygovDisplayLanguage, subscribeEasygovDisplayLanguage, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovDisplayLanguage, useEasygovHeaderContext, useEasygovSession, useEasygovVersionInfo, useRequireCustomerAccount };