@easygov/web-components 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,214 @@
+# @easygov/web-components
+
+Framework-agnostic custom elements for EasyGov 2.0, wrapping
+[`@easygov/react-components`](../react-components) as self-contained browser bundles via
+[`@r2wc/react-to-web-component`](https://github.com/bitovi/react-to-web-component). Use this
+package instead of `@easygov/react-components` when your app isn't React — Angular, Vue, plain
+HTML/JS, etc.
+
+Each bundle inlines React, ReactDOM, and its own copy of `@easygov/react-components`, so there is
+nothing else to install and no risk of a version clash with an app that happens to use React for
+something else.
+
+## Install
+
+```sh
+npm install @easygov/web-components
+```
+
+There are no runtime peer dependencies to install — React and ReactDOM are bundled in. (The
+`package.json` lists `react`/`react-dom` as peer dependencies purely so npm doesn't warn a
+React host app about a duplicate copy; you never need to satisfy them yourself.)
+
+## Usage
+
+Each custom element is a side-effecting subpath import — importing it registers the element:
+
+```ts
+import "@easygov/web-components/header"; // registers <eg-easygov-header>
+import "@easygov/web-components/footer"; // registers <eg-easygov-footer>
+```
+
+```html
+<eg-easygov-header></eg-easygov-header>
+
+<main>...</main>
+
+<eg-easygov-footer></eg-easygov-footer>
+```
+
+Import only the subpath(s) you need — an app using just the footer never pulls in the header's
+code. Both share one common chunk (React, the design tokens' fonts/CSS, `@easygov/react-components`
+itself), so it's fetched once regardless of how many elements you import.
+
+Each element renders into an open shadow root with the design system's styles and fonts attached
+automatically — no separate stylesheet or font import required, unlike
+`@easygov/react-components`.
+
+### `<eg-easygov-header>`
+
+No attributes. Auth, the display language, and the environment/version badges are all handled
+internally the same way they are in `@easygov/react-components` — see that package's README for
+the underlying `NEXT_PUBLIC_*` env var configuration, since it applies here too (see
+[Build-time configuration](#build-time-configuration) below for the web-components-specific
+wrinkle).
+
+No props are mapped, and none of the header's callback props (`onLanguageChange`, `onNavigate`,
+`onContextChange`, `onLogout`) exist here either — function props can't cross the custom-element
+boundary. Listen for the corresponding `CustomEvent`s instead:
+
+```js
+const header = document.querySelector("eg-easygov-header");
+
+header.addEventListener("languagechange", (e) => {
+  console.log(e.detail.locale); // 'de' | 'en' | 'fr' | 'it'
+});
+header.addEventListener("navigate", (e) => {
+  console.log(e.detail.path);
+});
+header.addEventListener("contextchange", (e) => {
+  const { contextJwt, claims } = e.detail; // decoded, NOT signature-verified — see below
+});
+header.addEventListener("sessionchange", (e) => {
+  console.log(e.detail.user);
+});
+```
+
+**`contextJwt`/`claims` are decoded but not verified.** Use them to prefill forms or drive
+rendering; a backend that receives `contextJwt` must verify it against core-backend's published
+JWKS before trusting any claim.
+
+### `<eg-easygov-footer>`
+
+No attributes, no props, no events — fully static content.
+
+### DisplayLanguage API
+
+The header owns the current display language (resolved from the `eg-display-language` cookie
+shared across every EasyGov subdomain, then the browser language, then `"de"`). Read or change it
+from the package root:
+
+```ts
+import {
+  getDisplayLanguage,
+  setDisplayLanguage,
+  subscribeDisplayLanguage,
+} from "@easygov/web-components";
+
+getDisplayLanguage(); // 'de' | 'en' | 'fr' | 'it' | ...
+setDisplayLanguage("fr"); // writes the shared cookie; every subscribed header re-renders
+const unsubscribe = subscribeDisplayLanguage(() => {
+  console.log("display language changed:", getDisplayLanguage());
+});
+```
+
+**Don't mix this with `@easygov/react-components`'s `useEasygovDisplayLanguage()` on the same
+page.** This bundle inlines its own copy of `@easygov/react-components`, so the two would read
+from different store instances and drift apart the moment a user picks a language. If a page
+already uses `@easygov/react-components` directly, use its hook/functions instead of this
+package's.
+
+### Publishing the business module's version
+
+A consuming app can publish its own version number so it shows up in the header's environment
+badge tooltip, alongside the library and backend versions:
+
+```ts
+import { setBusinessModuleVersion } from "@easygov/web-components";
+
+setBusinessModuleVersion("2.4.1");
+```
+
+Call it once at startup (or whenever your app's version is known); calling it again later simply
+updates the tooltip. Same "don't mix stores" caveat as above applies if the same page also uses
+`@easygov/react-components` directly.
+
+## Framework examples
+
+### Angular
+
+`apps/angular-demo` in this repo is a full working example — install `@easygov/web-components`
+as a real npm dependency (not `workspace:*`) and side-effect-import the subpaths you need, then
+wrap each custom element in a small Angular component so its events become `@Output()`s:
+
+```ts
+// main.ts
+import "@easygov/web-components/header";
+import "@easygov/web-components/footer";
+```
+
+```ts
+// components/easygov-header/easygov-header.component.ts
+import { AfterViewInit, Component, CUSTOM_ELEMENTS_SCHEMA, ElementRef, EventEmitter, OnDestroy, Output, ViewChild } from "@angular/core";
+
+const BRIDGED_EVENTS = ["languagechange", "navigate", "contextchange", "sessionchange"] as const;
+
+@Component({
+  selector: "app-easygov-header",
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<eg-easygov-header #host></eg-easygov-header>`,
+})
+export class EasygovHeaderComponent implements AfterViewInit, OnDestroy {
+  @ViewChild("host", { static: true }) private host!: ElementRef<HTMLElement>;
+  @Output() languagechange = new EventEmitter<CustomEvent>();
+  @Output() navigate = new EventEmitter<CustomEvent>();
+  @Output() contextchange = new EventEmitter<CustomEvent>();
+  @Output() sessionchange = new EventEmitter<CustomEvent>();
+
+  private readonly listeners = new Map<string, (event: Event) => void>();
+
+  ngAfterViewInit(): void {
+    for (const eventName of BRIDGED_EVENTS) {
+      const listener = (event: Event) => this[eventName].emit(event as CustomEvent);
+      this.listeners.set(eventName, listener);
+      this.host.nativeElement.addEventListener(eventName, listener);
+    }
+  }
+
+  ngOnDestroy(): void {
+    for (const [eventName, listener] of this.listeners) {
+      this.host.nativeElement.removeEventListener(eventName, listener);
+    }
+  }
+}
+```
+
+`CUSTOM_ELEMENTS_SCHEMA` is required on any Angular component template that renders a custom
+element directly, or the Angular compiler rejects the unknown tag.
+
+### Plain HTML / vanilla JS
+
+See `packages/web-components/demo/index.html` in this repo — run
+`pnpm --filter @easygov/web-components demo` after building, then open
+`http://localhost:4173/demo/` for a live local page exercising both elements, their events, and
+the DisplayLanguage API.
+
+## Build-time configuration
+
+`EasygovHeader` needs `NEXT_PUBLIC_CORE_ORIGIN` / `NEXT_PUBLIC_CORE_API_ORIGIN` /
+`NEXT_PUBLIC_OIDC_AUTHORITY` / `NEXT_PUBLIC_INFO_ORIGIN` on any host outside `*.easygov.swiss`
+(see `@easygov/react-components`'s README for what each does and when it's required).
+
+**Unlike `@easygov/react-components`, you cannot set these when *your* app builds** — this
+package ships a pre-built bundle with those values already inlined by tsup at the time
+`@easygov/web-components` itself was built and published (see this repo's
+`packages/web-components/tsup.config.ts` and the `@easygov/web-components#build` task in
+`turbo.json`). If your deployment target needs origins other than what the published package
+was built with, you have two options:
+
+- Rely on the automatic `*.easygov.swiss` subdomain derivation (no env vars needed there), or
+- Fork/rebuild this package yourself with the env vars set for your target, or use
+  `@easygov/react-components` directly instead, where `NEXT_PUBLIC_*` is inlined at *your*
+  app's build time.
+
+## Testing
+
+Components rendered by this package carry the same `data-slot` attributes as
+`@easygov/react-components` (see that package), but they live inside each element's shadow root — 
+an external Playwright suite must pierce the shadow boundary (e.g. 
+Playwright's `page.locator('eg-easygov-header').locator('...')`, which crosses open shadow roots 
+automatically) rather than querying `document` directly.
+
+## License
+
+MIT