weg-shared-layout 0.0.32 → 0.0.34

package/docs/angular-integration-guide.md

@@ -1,1035 +0,0 @@
-# Angular integration guide
-
-Step-by-step guide for **Angular 16+** (standalone or NgModule). Covers static fixtures, HTTP layout, auth, and common pitfalls.
-
-| Doc | When to use it |
-| --- | --- |
-| **This guide** | First integration, production setup, API mapping, testing, SSR |
-| **[angular.md](./angular.md)** | Short copy-paste quick start (same steps, fewer words) |
-| **[angular-16-compatibility.md](./angular-16-compatibility.md)** | TS 4.9 / `stencil-public-runtime` errors, subpath import / `moduleResolution` |
-| **[demo/angular16/README.md](../demo/angular16/README.md)** | In-repo Angular 16 app — **same imports as npm install** (copy-paste guide) |
-| **[weg-angular-demo](https://github.com/jobsac/weg-angular-demo)** | Runnable reference app (newer Angular) |
-
----
-
-## How to read this guide
-
-1. Follow **[Step-by-step integration](#step-by-step-integration)** in order — that is the complete happy path.
-2. Skim **[Layout data reference](#layout-data-reference)** when shaping CMS/API JSON.
-3. Use **[Optional sections](#optional-sections)** only when they match your app (separate API arrays, signals, SSR, tests, etc.).
-4. If something breaks, go to **[Troubleshooting](#troubleshooting)**.
-
-**Steps 6 and 7 include two variants each** — pick the one that matches your app:
-
-| Variant | Angular | State style |
-| --- | --- | --- |
-| **6A / 7A** | 16+ | Plain fields + RxJS `async` pipe (HTTP) |
-| **6B / 7B** | 16.1+ (signals) | `signal()` + `toSignal()` for HTTP |
-
-The web components are identical; only Angular template syntax differs (`layoutData` vs `layoutData()`).
-
----
-
-## Integration checklist
-
-Copy this list while integrating:
-
-- [ ] **Step 1** — `npm i weg-shared-layout`
-- [ ] **Step 2** — `defineCustomElements()` in `main.ts` **before** bootstrap
-- [ ] **Step 3** — TypeScript: `resolveJsonModule`, `skipLibCheck`, `moduleResolution` (`bundler` or `node16`) — see [Step 3](#step-3--typescript-import-layout-json)
-- [ ] **Step 4** — `src/app/auth.ts` with sign-in URL constants (host app, not from package)
-- [ ] **Step 5** — `CUSTOM_ELEMENTS_SCHEMA` on the shell `@Component` (or `@NgModule`) that owns `<weg-header>` / `<weg-footer>`
-- [ ] **Step 6** — Shell template with **`[layout]`** property binding (not `layout="..."`)
-- [ ] **Step 7** — Replace fixture with HTTP/CMS when ready; keep `{ header, footer }` object shape
-- [ ] **Step 8** — Header: `[signedIn]`, `[userName]`, `(wegAuthClick)` + `preventDefault()` if you handle auth
-- [ ] **Step 9** — Confirm in DevTools: `$0.layout` is an object on `<weg-header>`
-
----
-
-## What you are integrating
-
-`weg-shared-layout` ships two **Stencil Web Components**:
-
-| Tag | Purpose |
-| --- | --- |
-| `<weg-header>` | Header — bundled logo, CMS nav (signed out), built-in nav (signed in), Sign in / Manage Account / Sign out |
-| `<weg-footer>` | Footer — social links, menu, credits, copyright |
-
-They are **presentational**: they **do not** fetch data. Your Angular app loads layout JSON and passes it in.
-
-Angular treats them as **custom elements**. Bind JavaScript **properties** (square brackets in templates):
-
-```js
-header.layout = { header: { ... }, footer: { ... } };
-header.signedIn = true;
-header.userName = 'Alex';
-```
-
-The components do not depend on signals, RxJS, or standalone vs NgModule — only that values reach the element properties.
-
-### Requirements
-
-| Requirement | Notes |
-| --- | --- |
-| **Angular 16+** | Standalone and NgModule both work |
-| **Property binding** | `[layout]="obj"` — not `layout="{{ obj }}"` |
-| **`CUSTOM_ELEMENTS_SCHEMA`** | On every component template that uses the tags; **does not** cascade to routed children |
-| **One-time registration** | `defineCustomElements()` once per browser load (recommended) |
-| **TypeScript 5.0+** (Angular 16.1+) | Recommended for JSON/subpath imports; use `skipLibCheck` if staying on 4.9 — [angular-16-compatibility](./angular-16-compatibility.md) |
-
-**Runnable Angular 16 example (same imports as npm):** [demo/angular16/README.md](../demo/angular16/README.md).
-
----
-
-## Step-by-step integration
-
-These steps assume a **standalone** Angular app with `src/app/app.ts` + `src/app/app.html`. For **NgModule** bootstrap, see [Optional: NgModule bootstrap](#optional-ngmodule-bootstrap).
-
-### Step 1 — Install the package
-
-```bash
-npm i weg-shared-layout
-# or
-pnpm add weg-shared-layout
-```
-
----
-
-### Step 2 — Register custom elements (once, before bootstrap)
-
-**Recommended:** call the Stencil loader in `src/main.ts` **before** `bootstrapApplication`:
-
-```ts
-// src/main.ts
-import { bootstrapApplication } from '@angular/platform-browser';
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-import { appConfig } from './app/app.config';
-import { App } from './app/app';
-
-defineCustomElements();
-
-bootstrapApplication(App, appConfig).catch((err) => console.error(err));
-```
-
-**Alternative:** side-effect import only the tags you use (also once, before bootstrap). Pick one approach, not both:
-
-```ts
-import 'weg-shared-layout/weg-header';
-import 'weg-shared-layout/weg-footer';
-```
-
-If header/footer are empty but tags appear in the DOM, registration did not run or ran too late.
-
-Side-effect imports need **`moduleResolution": "bundler"`** (or `"node16"`). If you cannot change that, use the **loader only** — see [angular-16-compatibility.md](./angular-16-compatibility.md).
-
----
-
-### Step 3 — TypeScript: import layout JSON
-
-In **`tsconfig.json`** and/or **`tsconfig.app.json`** (Angular 16 + TypeScript 5.1 example — matches [demo/angular16](../demo/angular16/README.md)):
-
-```json
-{
-  "compilerOptions": {
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    "moduleResolution": "bundler"
-  },
-  "include": ["src/**/*.ts"]
-}
-```
-
-| Option | Why |
-| --- | --- |
-| `skipLibCheck` | Skips Stencil `stencil-public-runtime.d.ts` (TS 5 syntax) when on TS 4.9 |
-| `resolveJsonModule` | Allows `import … from 'weg-shared-layout/dummy-data.json'` |
-| `moduleResolution: "bundler"` | Resolves package `exports` (`loader`, `dummy-data.json`) |
-
-Use **`node16`** instead of **`bundler`** if required by your toolchain. Classic **`node`** does not resolve subpaths reliably.
-
-Create a shared layout type in `src/app/layout.types.ts`:
-
-```ts
-// src/app/layout.types.ts
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-
-/** Aligns with weg-shared-layout / CMS GET /api/layout shape */
-export type LayoutData = typeof layoutFixture;
-```
-
-During development you can import the package fixture:
-
-```ts
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-```
-
-Production: same shape from your API (e.g. [`GET /api/layout`](https://weg-payload-test.vercel.app/api/layout)).
-
-Types without JSON import:
-
-```ts
-import type { LayoutData } from 'weg-shared-layout/layout-data';
-```
-
-(requires `./layout-data` in package `exports` — see published version.)
-
----
-
-### Step 4 — Auth URLs in your app (not from the package)
-
-Create `src/app/auth.ts`. Host apps own sign-in/out URLs — do not import auth constants from `weg-shared-layout`.
-
-```ts
-// src/app/auth.ts
-export const HEADER_SIGN_IN = {
-  label: 'Sign in',
-  href: 'https://account.warwickemploymentgroup.com/account/login',
-};
-
-/** Where to send the user after sign-out (often same as login) */
-export const ACCOUNT_LOGIN_HREF = HEADER_SIGN_IN.href;
-```
-
-If your API omits a Sign in entry in `header.menu`, append `HEADER_SIGN_IN` when building layout — see Step 7.
-
----
-
-### Step 5 — Allow custom elements in templates
-
-Angular's compiler does not recognize `<weg-header>` / `<weg-footer>` unless you opt in.
-
-Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to the **shell** component whose template contains the tags (usually `App`):
-
-```ts
-// src/app/app.ts
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-
-@Component({
-  selector: 'app-root',
-  imports: [RouterOutlet],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  templateUrl: './app.html',
-})
-export class App {
-  // layout + auth — Step 6
-}
-```
-
-**Important:** If only `App` has the header/footer, only `App` needs the schema. Routed child components do **not** inherit it from a parent.
-
----
-
-### Step 6 — Shell component with layout (static fixture)
-
-Complete minimal shell (no HTTP yet). Use **6A** or **6B** — not both.
-
-#### Step 6A — Plain properties (Angular 16+)
-
-**`src/app/app.ts`:**
-
-```ts
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-
-import { ACCOUNT_LOGIN_HREF, HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-
-@Component({
-  selector: 'app-root',
-  imports: [RouterOutlet],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  templateUrl: './app.html',
-})
-export class App {
-  /** Same object for header and footer */
-  layoutData: LayoutData = layoutFixture;
-
-  signedIn = false;
-  userName?: string;
-
-  onAuthClick(event: Event): void {
-    const customEvent = event as CustomEvent<{ action: 'sign-in' | 'sign-out' }>;
-    customEvent.preventDefault();
-
-    if (customEvent.detail.action === 'sign-out') {
-      this.signedIn = false;
-      window.location.href = ACCOUNT_LOGIN_HREF;
-      return;
-    }
-
-    window.location.href = HEADER_SIGN_IN.href;
-  }
-}
-```
-
-**`src/app/app.html`:**
-
-```html
-<weg-header
-  [layout]="layoutData"
-  [signedIn]="signedIn"
-  [userName]="userName"
-  (wegAuthClick)="onAuthClick($event)"
-></weg-header>
-
-<main>
-  <router-outlet />
-</main>
-
-<weg-footer [layout]="layoutData"></weg-footer>
-```
-
-Binding rules (6A):
-
-| Correct | Wrong |
-| --- | --- |
-| `[layout]="layoutData"` | `layout="{{ layoutData }}"` (string attribute) |
-| `[signedIn]="signedIn"` | Omitting `signedIn` when you need signed-in nav |
-| No `()` on bindings | `layoutData()` — that is for **6B** only |
-
----
-
-#### Step 6B — Signals (Angular 16.1+)
-
-Same shell as 6A; bindings use `()` because values are signals.
-
-**`src/app/app.ts`:**
-
-```ts
-import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-
-import { ACCOUNT_LOGIN_HREF, HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-
-@Component({
-  selector: 'app-root',
-  imports: [RouterOutlet],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  templateUrl: './app.html',
-})
-export class App {
-  readonly layoutData = signal<LayoutData>(layoutFixture);
-
-  readonly signedIn = signal(false);
-  readonly userName = signal<string | undefined>(undefined);
-
-  onAuthClick(event: Event): void {
-    const customEvent = event as CustomEvent<{ action: 'sign-in' | 'sign-out' }>;
-    customEvent.preventDefault();
-
-    if (customEvent.detail.action === 'sign-out') {
-      this.signedIn.set(false);
-      this.userName.set(undefined);
-      window.location.href = ACCOUNT_LOGIN_HREF;
-      return;
-    }
-
-    window.location.href = HEADER_SIGN_IN.href;
-  }
-}
-```
-
-**`src/app/app.html`:**
-
-```html
-<weg-header
-  [layout]="layoutData()"
-  [signedIn]="signedIn()"
-  [userName]="userName()"
-  (wegAuthClick)="onAuthClick($event)"
-></weg-header>
-
-<main>
-  <router-outlet />
-</main>
-
-<weg-footer [layout]="layoutData()"></weg-footer>
-```
-
-Run the app — you should see header nav and footer. Continue to **Step 7A** or **7B** for HTTP.
-
----
-
-### Step 7 — Load layout from your API
-
-Use **7A** (RxJS `async` pipe) or **7B** (`toSignal`) — same `LayoutService` as below. Pick the pair that matches Step 6 (6A → 7A, 6B → 7B).
-
-**`src/app/layout.service.ts`** (shared by 7A and 7B):
-
-```ts
-import { Injectable } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { map, Observable } from 'rxjs';
-
-import { HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-
-@Injectable({ providedIn: 'root' })
-export class LayoutService {
-  constructor(private http: HttpClient) {}
-
-  /** CMS returns full { header, footer } object */
-  loadLayout(): Observable<LayoutData> {
-    return this.http.get<LayoutData>('/api/layout').pipe(
-      map((data) => this.ensureSignInMenu(data)),
-    );
-  }
-
-  private ensureSignInMenu(data: LayoutData): LayoutData {
-    const menu = data.header?.menu ?? [];
-    const hasSignIn = menu.some(
-      (item) =>
-        !item.items?.length &&
-        item.label?.trim().toLowerCase() === 'sign in',
-    );
-    if (hasSignIn) return data;
-    return {
-      ...data,
-      header: { ...data.header, menu: [...menu, HEADER_SIGN_IN] },
-    };
-  }
-}
-```
-
-Register `provideHttpClient()` in `app.config.ts` if not already present.
-
-#### Step 7A — HTTP with RxJS + `async` pipe (pairs with 6A)
-
-**`src/app/app.ts`:**
-
-```ts
-import { AsyncPipe } from '@angular/common';
-import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-import { Observable } from 'rxjs';
-
-import { ACCOUNT_LOGIN_HREF, HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-import { LayoutService } from './layout.service';
-
-@Component({
-  selector: 'app-root',
-  imports: [AsyncPipe, RouterOutlet],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  templateUrl: './app.html',
-})
-export class App {
-  layout$: Observable<LayoutData>;
-  signedIn = false;
-  userName?: string;
-
-  constructor(layoutService: LayoutService) {
-    this.layout$ = layoutService.loadLayout();
-  }
-
-  onAuthClick(event: Event): void {
-    const customEvent = event as CustomEvent<{ action: 'sign-in' | 'sign-out' }>;
-    customEvent.preventDefault();
-
-    if (customEvent.detail.action === 'sign-out') {
-      this.signedIn = false;
-      window.location.href = ACCOUNT_LOGIN_HREF;
-      return;
-    }
-
-    window.location.href = HEADER_SIGN_IN.href;
-  }
-}
-```
-
-**`src/app/app.html`:**
-
-```html
-@if (layout$ | async; as layout) {
-  <weg-header
-    [layout]="layout"
-    [signedIn]="signedIn"
-    [userName]="userName"
-    (wegAuthClick)="onAuthClick($event)"
-  ></weg-header>
-
-  <main>
-    <router-outlet />
-  </main>
-
-  <weg-footer [layout]="layout"></weg-footer>
-}
-```
-
-`@if (layout$ | async; as layout)` avoids a flash of empty header while the request is in flight. On older Angular without `@if`, use `*ngIf="layout$ | async as layout"`.
-
-Use `shareReplay(1)` on `layout$` if multiple subscribers need the same payload.
-
----
-
-#### Step 7B — HTTP with signals + `toSignal` (pairs with 6B)
-
-Requires **Angular 16.1+** (`@angular/core/rxjs-interop`).
-
-**`src/app/app.ts`:**
-
-```ts
-import { Component, CUSTOM_ELEMENTS_SCHEMA, inject, signal } from '@angular/core';
-import { toSignal } from '@angular/core/rxjs-interop';
-import { RouterOutlet } from '@angular/router';
-
-import { ACCOUNT_LOGIN_HREF, HEADER_SIGN_IN } from './auth';
-import { LayoutService } from './layout.service';
-
-@Component({
-  selector: 'app-root',
-  imports: [RouterOutlet],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  templateUrl: './app.html',
-})
-export class App {
-  private readonly layoutService = inject(LayoutService);
-
-  readonly layout = toSignal(this.layoutService.loadLayout());
-  readonly signedIn = signal(false);
-  readonly userName = signal<string | undefined>(undefined);
-
-  onAuthClick(event: Event): void {
-    const customEvent = event as CustomEvent<{ action: 'sign-in' | 'sign-out' }>;
-    customEvent.preventDefault();
-
-    if (customEvent.detail.action === 'sign-out') {
-      this.signedIn.set(false);
-      this.userName.set(undefined);
-      window.location.href = ACCOUNT_LOGIN_HREF;
-      return;
-    }
-
-    window.location.href = HEADER_SIGN_IN.href;
-  }
-}
-```
-
-**`src/app/app.html`:**
-
-```html
-@if (layout(); as layout) {
-  <weg-header
-    [layout]="layout"
-    [signedIn]="signedIn()"
-    [userName]="userName()"
-    (wegAuthClick)="onAuthClick($event)"
-  ></weg-header>
-
-  <main>
-    <router-outlet />
-  </main>
-
-  <weg-footer [layout]="layout"></weg-footer>
-}
-```
-
-`toSignal` bridges the HTTP `Observable` from `LayoutService` into a signal for the template. Session fields (`signedIn`, `userName`) stay as signals, same as Step 6B.
-
----
-
-### Step 8 — Header auth behaviour
-
-| Binding | Web component | Purpose |
-| --- | --- | --- |
-| `[layout]="..."` | `layout` | CMS nav when **signed out** |
-| `[signedIn]="..."` | `signed-in` | `true` → built-in signed-in nav (ignores CMS `header.menu`) |
-| `[userName]="..."` | `user-name` | First name on Manage Account when signed in |
-| `(wegAuthClick)="..."` | `wegAuthClick` | `detail.action`: `'sign-in'` \| `'sign-out'` |
-
-**Signed out** (`signedIn === false`):
-
-- Uses `layout.header.menu` — dropdown groups (`items`) and flat links (`href`), including Sign in
-- Logo **image** from `layout.header.logoSrc` (bundled if omitted); logo **link** always goes to WEG home
-
-**Signed in** (`signedIn === true`):
-
-- Built-in links: Find a job, Dashboard, Manage Account, Sign out
-- `userName` customizes Manage Account label
-
-Call `event.preventDefault()` in `onAuthClick` when **your** app handles navigation. Without `preventDefault()`, the component uses default redirects.
-
-Wire `signedIn` / `userName` from your session service (set `signedIn = true` and `userName` when the user logs in).
-
----
-
-### Step 9 — Verify in the browser
-
-1. Open DevTools → Elements → select `<weg-header>`.
-2. In the console:
-
-```js
-$0.layout      // must be a plain object, not undefined
-$0.signedIn    // boolean
-$0.userName    // string or undefined
-```
-
-3. If `layout` is missing or looks like `"[object Object]"`, you used attribute binding instead of `[layout]`.
-4. Footer: same `layout` object; only `layout.footer` is read.
-
----
-
-## Layout data reference
-
-Both tags accept one **`layout`** object with optional `header` and `footer` keys — **not** a bare array at the top level.
-
-### TypeScript shape
-
-```ts
-type LayoutLink = {
-  label: string;
-  href?: string;
-  target?: '_blank' | '_self' | '_parent' | '_top';
-  items?: LayoutLink[];
-};
-
-type LayoutHeaderData = {
-  logoSrc?: string;
-  menu?: LayoutLink[];
-};
-
-type LayoutFooterSocialLink = {
-  platform: 'LinkedIn' | 'Instagram' | 'TikTok' | 'YouTube';
-  href: string;
-};
-
-type LayoutFooterData = {
-  social?: LayoutFooterSocialLink[];
-  menu?: LayoutLink[][];
-  credits?: string;
-  copyright?: string;
-};
-
-type LayoutData = {
-  header?: Partial<LayoutHeaderData>;
-  footer?: Partial<LayoutFooterData>;
-};
-```
-
-Full example JSON:
-
-- **From npm:** `import layout from 'weg-shared-layout/dummy-data.json'`
-- **In this repo:** [`src/assets/dummy-data.json`](../src/assets/dummy-data.json)
-- **Live CMS sample:** [`GET /api/layout`](https://weg-payload-test.vercel.app/api/layout)
-
-### Abbreviated JSON
-
-```json
-{
-  "header": {
-    "logoSrc": "https://www.warwickemploymentgroup.com/assets/weg-logo.svg",
-    "menu": [
-      {
-        "label": "Find a job",
-        "items": [
-          { "label": "Graduates", "href": "https://example.com/jobs/graduates" }
-        ]
-      },
-      { "label": "Career advice", "href": "https://example.com/career-advice" },
-      { "label": "Register", "href": "https://example.com/register" },
-      { "label": "Sign in", "href": "https://example.com/login" }
-    ]
-  },
-  "footer": {
-    "social": [
-      { "platform": "LinkedIn", "href": "https://linkedin.com/company/example" }
-    ],
-    "menu": [
-      [{ "label": "About WEG", "href": "/about" }]
-    ],
-    "credits": "Warwick Employment Group …",
-    "copyright": "Copyright © Warwick Employment Group."
-  }
-}
-```
-
-### Which fields are used when
-
-| Field | Used when | Notes |
-| --- | --- | --- |
-| `header.logoSrc` | Signed **out** | Logo image URL; bundled if omitted |
-| `header.menu` | Signed **out** | Unified nav — groups use `items[]`, flat links use `href` |
-| `footer.social` | Always | `platform` must be `LinkedIn`, `Instagram`, `TikTok`, or `YouTube` exactly |
-| `footer.menu` | Always | `LayoutLink[][]` — one link array per column |
-| `footer.credits` | Always | Text below menu |
-| `footer.copyright` | Always | Copyright line |
-
-When **`signedIn` is true**, `<weg-header>` **ignores** `header.menu` from layout.
-
-### Property binding vs attributes
-
-```html
-<!-- Correct -->
-<weg-header [layout]="layoutData"></weg-header>
-
-<!-- Wrong for objects -->
-<weg-header layout="{{ layoutData }}"></weg-header>
-```
-
-The component can parse a JSON **string** for `layout`, but `[layout]="object"` is the Angular norm.
-
-### Invalid entries are silently dropped
-
-- Links without `label` or `href` are skipped
-- Menu groups with empty `items` are skipped
-- Unknown social `platform` values are skipped
-- Malformed input → empty sections (no throw) — inspect `$0.layout` in DevTools
-
----
-
-## Optional sections
-
-Read only what applies to your app.
-
-### Optional: API returns separate arrays (not one layout object)
-
-**Skip this section** if your API already returns `{ header: { ... }, footer: { ... } }`.
-
-The top-level `[layout]` binding must be an **object**, not an array:
-
-```ts
-// ❌ Will NOT work — nav stays empty
-const navLinks = [
-  { label: 'Career advice', href: '/career-advice' },
-];
-// template: [layout]="navLinks"
-```
-
-**✅** Put arrays **inside** the layout object:
-
-| Field | Array element shape |
-| --- | --- |
-| `header.menu` | `LayoutLink` — group with `items[]` or flat link with `href` |
-| `footer.social` | `{ platform, href }` |
-| `footer.menu` | `{ label, href }[]` per column |
-
-**`src/app/layout.service.ts` — merge multiple endpoints into one menu:**
-
-```ts
-import { Injectable } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { forkJoin, map, Observable } from 'rxjs';
-
-import { HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-
-@Injectable({ providedIn: 'root' })
-export class LayoutService {
-  constructor(private http: HttpClient) {}
-
-  loadLayoutFromParts(): Observable<LayoutData> {
-    return forkJoin({
-      menuGroups: this.http.get<NonNullable<LayoutData['header']>['menu']>(
-        '/api/nav/menu',
-      ),
-      flatLinks: this.http.get<NonNullable<LayoutData['header']>['menu']>(
-        '/api/nav/links',
-      ),
-      footer: this.http.get<LayoutData['footer']>('/api/footer'),
-    }).pipe(
-      map(({ menuGroups, flatLinks, footer }) => ({
-        header: {
-          menu: [...menuGroups, ...flatLinks, HEADER_SIGN_IN],
-        },
-        footer,
-      })),
-    );
-  }
-}
-```
-
-Bind the result the same way as Step 7.
-
----
-
-### Optional: Plain vs signals (cheat sheet)
-
-| | Step 6A / 7A (plain + RxJS) | Step 6B / 7B (signals) |
-| --- | --- | --- |
-| Angular | 16+ | 16.1+ |
-| Static layout | `layoutData = { ... }` | `layoutData = signal({ ... })` |
-| Template | `[layout]="layoutData"` | `[layout]="layoutData()"` |
-| HTTP layout | `layout$` + `\| async` | `layout = toSignal(loadLayout())` |
-| Update signed in | `this.signedIn = true` | `this.signedIn.set(true)` |
-
-Full code for both variants: **Step 6** and **Step 7** above, and [angular.md §6](./angular.md#6-layout-shell--pick-one).
-
----
-
-### Optional: Central layout service (BehaviorSubject)
-
-Use when multiple components need the same layout or you update it imperatively:
-
-```ts
-import { Injectable } from '@angular/core';
-import { BehaviorSubject } from 'rxjs';
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-
-import { HEADER_SIGN_IN } from './auth';
-import type { LayoutData } from './layout.types';
-
-@Injectable({ providedIn: 'root' })
-export class LayoutService {
-  private readonly layoutSubject = new BehaviorSubject<LayoutData>(layoutFixture);
-
-  readonly layout$ = this.layoutSubject.asObservable();
-
-  setLayout(data: LayoutData): void {
-    this.layoutSubject.next(this.ensureSignInMenu(data));
-  }
-
-  private ensureSignInMenu(data: LayoutData): LayoutData {
-    const menu = data.header?.menu ?? [];
-    const hasSignIn = menu.some(
-      (item) =>
-        !item.items?.length &&
-        item.label?.trim().toLowerCase() === 'sign in',
-    );
-    if (hasSignIn) return data;
-    return {
-      ...data,
-      header: { ...data.header, menu: [...menu, HEADER_SIGN_IN] },
-    };
-  }
-}
-```
-
----
-
-### Optional: Update layout at runtime
-
-Stencil watches the `layout` **property**. Assign a **new object reference** when data changes:
-
-```ts
-// Good
-this.layoutData = {
-  ...this.layoutData,
-  header: { ...this.layoutData.header, menu: newMenu },
-};
-
-// Risky — may not re-render
-this.layoutData.header!.menu!.push(newLink);
-```
-
-With `OnPush` and plain fields, call `ChangeDetectorRef.markForCheck()` after updates.
-
----
-
-### Optional: Imperative assignment (`@ViewChild`)
-
-Rare — use when property binding is blocked (legacy wrapper):
-
-```ts
-import {
-  AfterViewInit,
-  Component,
-  CUSTOM_ELEMENTS_SCHEMA,
-  ElementRef,
-  ViewChild,
-} from '@angular/core';
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-import type { LayoutData } from './layout.types';
-
-@Component({
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  template: `
-    <weg-header #header></weg-header>
-    <weg-footer #footer></weg-footer>
-  `,
-})
-export class ShellComponent implements AfterViewInit {
-  @ViewChild('header', { read: ElementRef }) headerRef!: ElementRef<HTMLElement>;
-  @ViewChild('footer', { read: ElementRef }) footerRef!: ElementRef<HTMLElement>;
-
-  layoutData: LayoutData = layoutFixture;
-
-  ngAfterViewInit(): void {
-    const header = this.headerRef.nativeElement as HTMLElement & {
-      layout?: LayoutData;
-    };
-    header.layout = this.layoutData;
-    (this.footerRef.nativeElement as HTMLElement & { layout?: LayoutData }).layout =
-      this.layoutData;
-  }
-}
-```
-
----
-
-### Optional: NgModule bootstrap
-
-**`src/main.ts`:**
-
-```ts
-import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-import { AppModule } from './app/app.module';
-
-defineCustomElements();
-
-platformBrowserDynamic()
-  .bootstrapModule(AppModule)
-  .catch((err) => console.error(err));
-```
-
-**`src/app/app.module.ts`:**
-
-```ts
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { BrowserModule } from '@angular/platform-browser';
-
-import { App } from './app';
-
-@NgModule({
-  declarations: [App],
-  imports: [BrowserModule],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
-  bootstrap: [App],
-})
-export class AppModule {}
-```
-
-Steps 4–9 are the same; declare the shell component in `declarations` instead of `imports: [App]`.
-
----
-
-### Optional: Testing
-
-In test setup:
-
-```ts
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-beforeAll(() => {
-  defineCustomElements();
-});
-```
-
-Before assertions:
-
-```ts
-await Promise.all([
-  customElements.whenDefined('weg-header'),
-  customElements.whenDefined('weg-footer'),
-]);
-
-fixture.detectChanges();
-await fixture.whenStable();
-
-const header = fixture.nativeElement.querySelector('weg-header') as HTMLElement & {
-  layout?: LayoutData;
-};
-
-expect(
-  header.layout?.header?.menu?.some(
-    (item) => item.label === 'Sign in' && item.href === HEADER_SIGN_IN.href,
-  ),
-).toBe(true);
-```
-
-Full example: [weg-angular-demo `app.spec.ts`](https://github.com/jobsac/weg-angular-demo/blob/main/src/app/app.spec.ts).
-
----
-
-### Optional: Server-side rendering (SSR)
-
-Guard registration in `main.ts`:
-
-```ts
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-if (typeof window !== 'undefined') {
-  defineCustomElements();
-}
-```
-
-Layout JSON can be fetched on the server; custom elements render after client hydration.
-
----
-
-## Footer
-
-`<weg-footer>` only needs `[layout]` with the same object as the header:
-
-```html
-<weg-footer [layout]="layoutData"></weg-footer>
-```
-
-External `https://` links open in a new tab automatically.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-| --- | --- | --- |
-| `'weg-header' is not a known element` | Missing schema | `CUSTOM_ELEMENTS_SCHEMA` on the component that owns the template |
-| Header/footer completely empty | Not registered | `defineCustomElements()` before bootstrap, or tag side-effect imports |
-| Tags render, nav empty | Wrong `layout` | `[layout]="..."` with object `{ header?, footer? }` |
-| Passed array to `[layout]` | Top-level must be object | `{ header: { menu: myArray } }` — see [Optional: API returns separate arrays](#optional-api-returns-separate-arrays-not-one-layout-object) |
-| Auth always Sign in | `signedIn` not bound / false | Bind session; set `true` when logged in |
-| Generic Manage Account | `userName` missing | Pass first name when `signedIn` is true |
-| Layout changes ignored | In-place mutation | New object reference |
-| Brief empty header with `async` | Observable not emitted yet | `@if (layout$ \| async; as layout)` or `BehaviorSubject` default |
-| Tests fail | Elements undefined | `defineCustomElements()` in `beforeAll` |
-| SSR `document is not defined` | Loader on server | `typeof window !== 'undefined'` guard |
-| Missing social icons | Bad `platform` | Exactly `LinkedIn`, `Instagram`, `TikTok`, `YouTube` |
-| Missing menu item | Normalization | Non-empty `label` and valid `items` or `href` |
-| `Mixin<const …>` / TS1139 in `stencil-public-runtime.d.ts` | TS 4.9 parsing Stencil 5 syntax | `skipLibCheck: true` and/or TypeScript 5.0+ — see **[angular-16-compatibility](./angular-16-compatibility.md)** |
-| Cannot resolve `weg-shared-layout/weg-header` | `moduleResolution: "node"` | Use `defineCustomElements` from `weg-shared-layout/loader`, or set `bundler` / `node16` — see **[angular-16-compatibility](./angular-16-compatibility.md)** |
-
-### DevTools
-
-```js
-$0.layout
-$0.signedIn
-$0.userName
-```
-
----
-
-## Quick reference
-
-### File map (standalone app)
-
-| File | Role |
-| --- | --- |
-| `src/main.ts` | `defineCustomElements()` then bootstrap |
-| `tsconfig.json` / `tsconfig.app.json` | `skipLibCheck`, `resolveJsonModule`, `moduleResolution: bundler` (or `node16`) |
-| `src/app/auth.ts` | `HEADER_SIGN_IN`, `ACCOUNT_LOGIN_HREF` |
-| `src/app/layout.types.ts` | `export type LayoutData = typeof layoutFixture` |
-| `src/app/layout.service.ts` | HTTP / API mapping (Step 7, optional arrays) |
-| `src/app/app.ts` | Shell: schema, layout, auth handler |
-| `src/app/app.html` | `<weg-header>`, `<router-outlet>`, `<weg-footer>` |
-
-### Minimal template
-
-```html
-<weg-header
-  [layout]="layoutData"
-  [signedIn]="signedIn"
-  [userName]="userName"
-  (wegAuthClick)="onAuthClick($event)"
-></weg-header>
-
-<router-outlet></router-outlet>
-
-<weg-footer [layout]="layoutData"></weg-footer>
-```
-
-### Related docs
-
-- [Documentation index](./README.md)
-- [Angular 16 / TypeScript 4.9 compatibility](./angular-16-compatibility.md)
-- [In-repo Angular 16 demo](../demo/angular16/README.md)
-- [Quick start (angular.md)](./angular.md)
-- [Package readme](../readme.md)
-- [Plain HTML / vanilla JS](./vanilla.md)
-- [React SPA](./react.md)
-- [External reference app (newer Angular)](https://github.com/jobsac/weg-angular-demo)