@easygov/react-components 0.10.0 → 0.12.0

package/README.md

@@ -76,9 +76,10 @@ that runs it.
 
 ### Reading the header context
 
-The header resolves the signed-in user, the selected customer account, the running process and
-its ancestor chain (if the URL addresses a sub-process) from core-backend and publishes them to
-consumers:
+The header sends the current screen URL (origin and path) to core-backend, which resolves the
+signed-in user, the selected customer account, the ServiceApp the screen belongs to, and the running
+process or the parent process a sub-process is being created under. The header publishes the result
+to consumers:
 
 ```tsx
 import { useEasygovHeaderContext } from '@easygov/react-components';
@@ -86,27 +87,39 @@ import { useEasygovHeaderContext } from '@easygov/react-components';
 function ContactForm() {
   const { claims } = useEasygovHeaderContext();
   const account = claims?.customerAccount;
-  const parentProcess = claims?.parentProcesses?.[0];
+  const parentProcessId = claims?.parentProcessId;
 
   return (
     <form>
       <input defaultValue={claims?.currentUser.firstName ?? ''} />
       <input defaultValue={account?.label ?? ''} />
       {account?.accountType === 'ORGANIZATION' && <input defaultValue={account.uid ?? ''} />}
-      <input defaultValue={parentProcess?.id ?? ''} />
+      <input defaultValue={parentProcessId ?? ''} />
     </form>
   );
 }
 ```
 
-`claims.parentProcesses` lists the ancestors of the addressed Behördengang, nearest first — index
-0 is the direct parent, ascending toward the root — and is absent (not `[]`) when there is none.
-If it is present while `claims.process` is absent, a sub-process is about to be created under
-`parentProcesses[0]`, which is then the addressed Process itself and not a selected Behördengang.
-Each `SelectedProcess` (in `claims.process` and `claims.parentProcesses`) also carries its own
-`parentProcessId` — the global identifier of its parent, absent for a top-level Behördengang —
-so a consumer can identify ancestry per node after flattening `parentProcesses` into a map,
-without relying solely on the array's ordering.
+`claims.serviceApp` is the ServiceApp the current screen belongs to, resolved by core from the URL's
+subdomain and path. It is absent on core and info pages and on a URL that matches no registered
+ServiceApp.
+
+`claims.process` and `claims.parentProcessId` are mutually exclusive. `process` is the Behördengang
+the URL selects (`/process/{id}`); it references its ServiceApp by `serviceAppId` and its own parent
+by `parentProcessId`, absent for a top-level Behördengang. `parentProcessId` at the top level is the
+Behördengang a sub-process is about to be created under (`/parentprocess/{id}`) — not a selected
+Behördengang. Neither is present when the URL addresses no process. The context carries no ancestor
+chain and no full parent object, because it is forwarded as an HTTP header where 4/8 KB size limits
+apply.
+
+For an Agent (Mitwirkende/r), `customerAccount.managementRole.servicePermission` is the Agent's
+permission on the current ServiceApp (`READ_ONLY`, `EDIT` or `AUTHORIZE`). It is absent for a
+SuperAgent, on a screen without a current ServiceApp, for a ServiceApp with the individual permission
+model (the fach module manages those rights itself), and when the Agent holds no permission on the
+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.
 
 `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`

package/dist/easygov.d.mts

@@ -326,11 +326,7 @@ declare function getAuthStatus(): AuthStatus;
 declare function requireSession(): void;
 
 type ManagementRoleType = 'SUPER_AGENT' | 'AGENT';
-/**
- * Verification level of a customer account's identity, and — as `ServiceApp.requiredAccountStatus`
- * — the minimum level a service demands. One type for both because the knockout rule compares
- * them to each other.
- */
+/** Verification level of a customer account's identity. */
 type AccountVerificationStatus = 'NOT_VERIFIED' | 'VERIFIED';
 /**
  * Verification of a management-role grant. Same values as `AccountVerificationStatus` today, but
@@ -339,16 +335,33 @@ type AccountVerificationStatus = 'NOT_VERIFIED' | 'VERIFIED';
  */
 type ManagementRoleStatus = 'NOT_VERIFIED' | 'VERIFIED';
 type ProcessStatus = 'PRELIMINARY' | 'REQUEST_IN_PROGRESS' | 'REQUEST_COMPLETED' | 'SERVICE_PROVISION_PENDING' | 'FINISHED' | 'CANCELED';
+/** An Agent's permission level on one ServiceApp (Leistungsberechtigung). */
+type PermissionLevel = 'READ_ONLY' | 'EDIT' | 'AUTHORIZE';
+/**
+ * An Agent's ServicePermission for the current ServiceApp. Decoded from the context JWT, signature
+ * unverified: safe to render, never to authorize.
+ */
+interface ServicePermission {
+    /** Always the current ServiceApp's id (`HeaderContextClaims.serviceApp.id`). */
+    serviceAppId: string;
+    permissionLevel: PermissionLevel;
+}
 /**
  * The caller's management role on the selected account: SUPER_AGENT (Kontoverwalter/in,
- * unrestricted) or AGENT (Mitwirkende/r, restricted by per-service permissions, which this
- * context does NOT carry).
+ * unrestricted) or AGENT (Mitwirkende/r, restricted by per-service permissions).
  * @see HeaderContextClaims for unverified-claims boundary; roleType and status must not drive authorization.
  */
 interface ManagementRole {
     roleType: ManagementRoleType;
     /** Only present for SUPER_AGENT. */
     status?: ManagementRoleStatus;
+    /**
+     * Only for an AGENT, and only for the current ServiceApp. Absent for a SUPER_AGENT, on a screen
+     * without a current ServiceApp, for an app with the individual permission model (the fach module
+     * manages those rights), and when the Agent holds no permission on the app. Absent never means
+     * "allowed".
+     */
+    servicePermission?: ServicePermission;
 }
 interface CustomerAccountBase {
     id: string;
@@ -377,22 +390,27 @@ interface IndividualAccount extends CustomerAccountBase {
  */
 type SelectedCustomerAccount = OrganizationAccount | IndividualAccount;
 /**
- * The selected Behördengang with its resolved ServiceApp.
+ * The ServiceApp the current screen belongs to, resolved by core from the screen URL.
+ * Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+interface ServiceApp {
+    id: string;
+    /** The fach module, not core, manages the Agents' rights for this ServiceApp. */
+    individualServicePermissionModel: boolean;
+}
+/**
+ * The selected Behördengang. Its ServiceApp is a reference only; on a screen of that ServiceApp
+ * it equals `HeaderContextClaims.serviceApp.id`.
  * Decoded from the context JWT, signature unverified: safe to render, never to authorize.
  */
 interface SelectedProcess {
     id: string;
     status: ProcessStatus;
-    serviceApp: {
-        id: string;
-        /** Minimum `CustomerAccount.status` the service requires (knockout). */
-        requiredAccountStatus: AccountVerificationStatus;
-        individualServicePermissionModel: boolean;
-    };
+    serviceAppId: string;
     /**
-     * Global identifier of this process's own parent. Absent for a top-level Behördengang.
-     * Lets a client identify ancestry per node — e.g. after flattening `parentProcesses` into a
-     * map — without relying solely on that array's documented ordering.
+     * Global identifier of this process's own parent. Absent for a top-level Behördengang. This
+     * reference is the only representation of a selected process's parent: the context carries no
+     * ancestor chain.
      */
     parentProcessId?: string;
 }
@@ -419,16 +437,21 @@ interface UserProfile {
 interface HeaderContextClaims {
     currentUser: UserProfile;
     customerAccount?: SelectedCustomerAccount;
+    /**
+     * The ServiceApp the current screen belongs to. Absent on core and info pages and on a URL that
+     * matches no registered ServiceApp.
+     */
+    serviceApp?: ServiceApp;
+    /**
+     * The Behördengang the URL selects (`/process/{id}`). Mutually exclusive with `parentProcessId`.
+     */
     process?: SelectedProcess;
     /**
-     * Ancestors of the addressed Behördengang, nearest first: index 0 is the direct parent,
-     * ascending toward the root. Absent — not an empty array — when there is none.
-     *
-     * Present while `process` is absent means a sub-process is about to be created under
-     * `parentProcesses[0]`, which is then the addressed Process itself and NOT a selected
-     * Behördengang. That is the `/parentprocess/{id}` URL form.
+     * The Behördengang a sub-process is about to be created under (`/parentprocess/{id}`), by id
+     * only. Mutually exclusive with `process`. A selected process's own parent is
+     * `process.parentProcessId`.
      */
-    parentProcesses?: SelectedProcess[];
+    parentProcessId?: string;
 }
 
 interface EasygovHeaderContext {
@@ -665,4 +688,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 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, 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 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 };