@easygov/react-components 0.4.8 → 0.5.0

package/README.md

@@ -114,6 +114,67 @@ document.addEventListener('contextchange', (e) => {
 that receives `contextJwt` must verify its signature against core-backend's published JWKS
 before trusting a claim.
 
+### Reading the display language
+
+The header owns the display language and publishes it the same way. It resolves from a cookie
+shared across every EasyGov subdomain, then the browser language, then `'de'` — so a language
+picked on the info module still applies after navigating to core or a Fachmodul:
+
+```tsx
+import { useEasygovDisplayLanguage } from '@easygov/react-components';
+
+function Greeting() {
+  const language = useEasygovDisplayLanguage(); // 'de' | 'en' | 'fr' | 'it'
+  return <p>{greetings[language]}</p>;
+}
+```
+
+Unlike `useEasygovHeaderContext`, this never returns a placeholder. The value needs no network
+call, so it is correct on first paint and even before an `EasygovHeader` has mounted. Outside a
+component, `getEasygovDisplayLanguage()` returns the same value and
+`subscribeEasygovDisplayLanguage(fn)` notifies you when it changes.
+
+The cookie is written **only** when the user picks a language in the header's switcher, never
+when the browser language is auto-detected. That is deliberate: it keeps the browser language a
+live default, so a user who has never made an explicit choice follows their browser even if
+they change it later.
+
+A module that has to set the language itself — a `/fr/…` route, say — calls the setter rather
+than rendering a second picker:
+
+```ts
+import { setEasygovDisplayLanguage } from '@easygov/react-components';
+
+setEasygovDisplayLanguage('fr');
+```
+
+That writes the same cookie the switcher writes, so there is exactly one source of truth and
+every subscribed module re-renders with it.
+
+Outside React — including `<eg-easygov-header>` — listen on the header element:
+
+```js
+document.querySelector('eg-easygov-header')
+  .addEventListener('languagechange', (e) => {
+    const { locale } = e.detail;
+  });
+```
+
+**Listen on the element, never on `window`.** The event bubbles and is `composed`, so it does
+reach `window` — where it is indistinguishable from the browser's *own* `languagechange` event,
+which fires when the user changes their OS language and carries no `detail`. A `window` listener
+reading `e.detail.locale` throws as soon as that happens.
+
+**A page using `<eg-easygov-header>` must not read the language through the npm hook.** That
+bundle is self-contained and inlines its own copy of this library, so the hook would resolve to
+a different store instance than the element is using, and the two drift apart the moment someone
+picks a language. Use the event above, or `easygov.getDisplayLanguage()` on the global the bundle
+defines.
+
+**Upgrading from 0.4.x:** the `locale` prop and the `locale` attribute are gone. The header owns
+the language now — read it with `useEasygovDisplayLanguage()`, set it with
+`setEasygovDisplayLanguage()`.
+
 ## License
 
 MIT

package/dist/easygov.d.mts

@@ -496,8 +496,17 @@ declare function useEasygovAuthStatus(): AuthStatus;
  * against core-backend's published JWKS.
  */
 declare function useEasygovHeaderContext(): EasygovHeaderContext;
+/**
+ * The current DisplayLanguage (EGOV-1451). Resolved as: the `eg-display-language` cookie shared
+ * across every EasyGov subdomain, else the browser language, else "de". The cookie is written only
+ * on an explicit pick in the header's switcher, so the browser-language default stays live until
+ * the user overrides it.
+ *
+ * Unlike useEasygovHeaderContext this never returns a placeholder: the value needs no network
+ * call, so a module can read it before any header has mounted.
+ */
+declare function useEasygovDisplayLanguage(): Locale;
 interface EasygovHeaderProps {
-    readonly locale?: Locale;
     readonly onLanguageChange?: (locale: Locale) => void;
     readonly onNavigate?: (path: string) => void;
     /**
@@ -524,7 +533,7 @@ interface EasygovHeaderProps {
     readonly onContextChange?: (contextJwt: string, claims: HeaderContextClaims) => void;
     readonly onLogout?: () => void;
 }
-declare function EasygovHeader({ locale: localeProp, onLanguageChange, onNavigate, onContextChange, onLogout, }: EasygovHeaderProps): React__default.JSX.Element;
+declare function EasygovHeader({ onLanguageChange, onNavigate, onContextChange, onLogout, }: EasygovHeaderProps): React__default.JSX.Element;
 interface RequireSessionProps {
     readonly children: React__default.ReactNode;
     readonly fallback?: React__default.ReactNode;
@@ -538,4 +547,30 @@ interface RequireCustomerAccountProps {
 }
 declare function RequireCustomerAccount({ children, onNavigate, }: RequireCustomerAccountProps): React__default.JSX.Element;
 
-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, 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 ProcessStatus as HeaderContextProcessStatus, 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, headingVariants, requireSession, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovHeaderContext, useEasygovSession, useRequireCustomerAccount };
+/**
+ * The current DisplayLanguage. Safe to call at any time, including before any EasygovHeader has
+ * mounted — it resolves cookie -> browser language -> "de" with no I/O. Identity is a plain
+ * string, so it is a valid `useSyncExternalStore` snapshot.
+ *
+ * Caching begins only once listeners are installed, i.e. after the first
+ * `subscribeEasygovDisplayLanguage`. Until then every call re-resolves, because nothing would
+ * invalidate a cache: a module that imports this getter and polls it without ever subscribing —
+ * exactly the second-bundle-instance topology the sync event exists for — would otherwise be
+ * pinned to the first value it ever read, for the life of the page. Installing from here is not an
+ * option: React calls this during render, which must stay side-effect free.
+ */
+declare function getEasygovDisplayLanguage(): Locale;
+/**
+ * Sets the DisplayLanguage as an explicit user choice: writes the cookie, updates this store, and
+ * announces it to sibling bundle instances. Called by the header's language switcher, and
+ * available to modules that must set the language themselves (e.g. a deep link into a /fr/… route)
+ * — going through the same path is what keeps one source of truth.
+ *
+ * The cookie is written ONLY here, never when the browser language is auto-detected. That is what
+ * keeps "default is the browser language" true: baking a detected language into the cookie on
+ * first page view would freeze it for a user who later changes their browser.
+ */
+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, 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 ProcessStatus as HeaderContextProcessStatus, 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, setEasygovDisplayLanguage, subscribeEasygovDisplayLanguage, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovDisplayLanguage, useEasygovHeaderContext, useEasygovSession, useRequireCustomerAccount };