weg-shared-layout 0.0.27 → 0.0.29

package/docs/angular-16-compatibility.md

@@ -1,250 +1,250 @@
-# Angular 16 compatibility
-
-Guide for teams on **Angular 16** who see TypeScript errors from `weg-shared-layout` in `node_modules`, or who cannot resolve subpath imports like `weg-shared-layout/weg-header`.
-
-| Doc | Use when |
-| --- | --- |
-| **[angular-integration-guide.md](./angular-integration-guide.md)** | Full integration steps |
-| **[angular.md](./angular.md)** | Quick start |
-| **[demo/angular16/README.md](../demo/angular16/README.md)** | Copy-paste Angular 16 app (npm-style imports) |
-| **This doc** | `stencil-public-runtime.d.ts` / `Mixin<const …>` errors, subpath import resolution, layout typing on TS 4.9 |
-
----
-
-## Short answers
-
-### Is `src/types/layout-data.ts` using `type` the problem?
-
-**No.** Those definitions compile to plain `.d.ts` shapes. They do not use TypeScript 5-only syntax.
-
-The errors you see point at **`node_modules/weg-shared-layout/dist/types/stencil-public-runtime.d.ts`**. That file is **generated by Stencil** when the package is built, not authored from `layout-data.ts`.
-
-### Can we switch to `interface` or `class` instead?
-
-You can use **`interface`** in your **Angular app** for the same fields (see [Layout types in your app](#layout-types-in-your-app)). Changing the library from `type` to `interface` **does not fix** the Stencil `Mixin<const …>` errors, because Angular still type-checks (or parses) Stencil’s runtime declarations when you import from the package entry or component subpaths that pull in `components.d.ts`.
-
-**`class`** is not a good fit here: layout payloads are JSON-shaped data, not class instances.
-
-String unions (e.g. `'sign-in' | 'sign-out'`) must stay as **`type` aliases** in TypeScript; they cannot be expressed as interfaces.
-
----
-
-## Error 1: `Mixin<const TMixins …>` / TS1139 in `stencil-public-runtime.d.ts`
-
-### What it means
-
-Stencil 4.x ships declaration files that use **TypeScript 5.0+** features, including **`const` type parameters** on generics:
-
-```ts
-export declare function Mixin<const TMixins extends readonly MixinFactory[]>(...): …;
-```
-
-If your app uses **TypeScript 4.9.x** (common on Angular 16.0–16.1 without a manual upgrade), the compiler **cannot parse** that line and reports many follow-on errors (TS1139, TS1005, etc.).
-
-This is unrelated to whether layout shapes are declared with `type`, `interface`, or `class`.
-
-### Fix A (recommended): Enable `skipLibCheck`
-
-In the Angular app’s root **`tsconfig.json`** (or `tsconfig.app.json` if that is where `compilerOptions` live):
-
-```json
-{
-  "compilerOptions": {
-    "skipLibCheck": true
-  }
-}
-```
-
-This tells TypeScript to **skip type-checking of all `.d.ts` files**, including Stencil’s. Your app source is still checked; only third-party declarations are skipped.
-
-Angular CLI **newer workspaces** often set this already. Older HeroJobs-style projects may have it **missing** — add it and rebuild.
-
-### Fix B: Use TypeScript 5.0+ (within Angular 16’s range)
-
-Angular **16.1+** supports TypeScript **`>=4.9.3` and `<5.2.0`**. Upgrade the app’s `typescript` devDependency to **5.0.x or 5.1.x** (match your exact `@angular/core` patch — see [Angular version compatibility](https://angular.dev/reference/versions)).
-
-Example:
-
-```bash
-npm i -D typescript@~5.1.6
-```
-
-Then confirm:
-
-```bash
-npx tsc --version
-```
-
-You should see **5.0+**. The `const` type parameter syntax will parse correctly even without relying only on `skipLibCheck`.
-
-### Fix C: Import layout types without the Stencil graph
-
-If you only need **`LayoutData`** (and related names) and want to avoid pulling `components.d.ts` → `stencil-public-runtime.d.ts`, import from the **types-only** subpath (package **0.0.24+**, or current main after publish):
-
-```ts
-import type { LayoutData, LayoutHeaderAuthAction } from 'weg-shared-layout/layout-data';
-```
-
-Requires **`moduleResolution`**: `"bundler"`, `"node16"`, or `"nodenext"` (see [Error 2](#error-2-cannot-find-module-weg-shared-layoutweg-header)). The `./layout-data` export is defined in this repo’s `package.json`; use a published version that includes it, or link the package locally while testing.
-
-Alternatively, keep the existing pattern from the integration guide — no import from the package at all:
-
-```ts
-import layoutFixture from 'weg-shared-layout/dummy-data.json';
-export type LayoutData = typeof layoutFixture;
-```
-
-That ties your app type to the fixture shape and never touches Stencil’s runtime `.d.ts` files.
-
-### What we are not changing in the library (for now)
-
-Replacing `type` with `interface` in `layout-data.ts` would be a **cosmetic** API change for consumers and **would not remove** `stencil-public-runtime.d.ts` from the published tarball. The durable fixes are **consumer `tsconfig`** (Fix A/B) or **types-only imports** (Fix C).
-
----
-
-## Error 2: Cannot find module `weg-shared-layout/weg-header`
-
-Typical message:
-
-```text
-Cannot find module or type declarations for side-effect import of 'weg-shared-layout/weg-header'.
-There are types at '.../node_modules/weg-shared-layout/dist/components/weg-header.d.ts',
-but this result could not be resolved under your current 'moduleResolution' setting.
-Consider updating to 'node16', 'nodenext', or 'bundler'.
-```
-
-### What it means
-
-`weg-shared-layout` exposes components via the **`exports`** field in `package.json` (subpaths like `./weg-header`). **Classic** `"moduleResolution": "node"` (still common in Angular 16 apps) does **not** resolve those subpaths the same way, even when the `.d.ts` files exist on disk.
-
-### Fix A (recommended): Use the Stencil loader
-
-In **`src/main.ts`**, register all components **once before** `bootstrapApplication`:
-
-```ts
-import { defineCustomElements } from 'weg-shared-layout/loader';
-
-defineCustomElements();
-
-// then bootstrapApplication(...)
-```
-
-The loader path is documented in the main integration guide and avoids per-tag side-effect imports.
-
-### Fix B: Modernize `moduleResolution`
-
-In **`tsconfig.json`** (app root), set:
-
-```json
-{
-  "compilerOptions": {
-    "moduleResolution": "bundler"
-  }
-}
-```
-
-Angular **17+** schematics often use `bundler`. On **Angular 16**, `bundler` is supported by TypeScript 5.0+; with TS 4.9, prefer **`"node16"`** or **`"nodenext"`** if `bundler` is not available.
-
-Then side-effect imports can work:
-
-```ts
-import 'weg-shared-layout/weg-header';
-import 'weg-shared-layout/weg-footer';
-```
-
-Use **one** registration strategy: loader **or** side-effect imports, not both.
-
-### Fix C: Stay on loader only
-
-If you cannot change `moduleResolution` (team policy, older tooling), **do not** use `import 'weg-shared-layout/weg-header'`. Use **`defineCustomElements()`** from `weg-shared-layout/loader` only.
-
----
-
-## Layout types in your app
-
-Three supported patterns (pick one):
-
-| Pattern | Example | Stencil `.d.ts` pulled? |
-| --- | --- | --- |
-| **Fixture-derived type** (default in guides) | `export type LayoutData = typeof layoutFixture` | No (only JSON + your file) |
-| **Package types subpath** | `import type { LayoutData } from 'weg-shared-layout/layout-data'` | No |
-| **Local interfaces** | Copy shapes into `layout.types.ts` | No |
-
-Example local interfaces (equivalent to package shapes; adjust if your API differs):
-
-```ts
-export interface LayoutLink {
-  label: string;
-  href?: string;
-  target?: '_blank' | '_self' | '_parent' | '_top';
-  items?: LayoutLink[];
-}
-
-export interface LayoutHeaderData {
-  logoSrc?: string;
-  menu?: LayoutLink[];
-}
-
-export type LayoutHeaderAuthAction = 'sign-in' | 'sign-out';
-
-export interface LayoutFooterSocialLink {
-  platform: 'LinkedIn' | 'Instagram' | 'TikTok' | 'YouTube';
-  href: string;
-}
-
-export interface LayoutFooterData {
-  menu?: LayoutLink[][];
-  social?: LayoutFooterSocialLink[];
-  credits?: string;
-  copyright?: string;
-}
-
-export interface LayoutData {
-  header?: Partial<LayoutHeaderData>;
-  footer?: Partial<LayoutFooterData>;
-}
-```
-
----
-
-## Recommended `tsconfig` snippet (Angular 16 + this package)
-
-```json
-{
-  "compilerOptions": {
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    "moduleResolution": "bundler"
-  }
-}
-```
-
-Use **`node16`** instead of **`bundler`** if you must stay on TypeScript 4.9.
-
-Pair with **`defineCustomElements()`** in `main.ts` and **`CUSTOM_ELEMENTS_SCHEMA`** on the shell component — unchanged from the main integration guide.
-
----
-
-## Checklist for HeroJobs / similar Angular 16 apps
-
-1. Confirm TypeScript version: `npx tsc --version` (4.9 vs 5.x).
-2. Add or verify **`skipLibCheck": true`**.
-3. Set **`moduleResolution`** to `bundler` or `node16`, **or** switch to **`weg-shared-layout/loader`** only.
-4. Prefer **`export type LayoutData = typeof layoutFixture`** or **`weg-shared-layout/layout-data`** for typing — avoid `import type { LayoutData } from 'weg-shared-layout'` if you still see Stencil errors and cannot use `skipLibCheck`.
-5. Rebuild: `ng build` / CI pipeline.
-
----
-
-## In-repo Angular 16 demo
-
-Runnable app: **[demo/angular16/README.md](../demo/angular16/README.md)** — same imports as a published npm install (`weg-shared-layout/dummy-data.json`, `weg-shared-layout/loader`); only the `package.json` dependency line differs (`file:../..` vs `^0.0.x`). Run with `npm run demo:angular16` from repo root.
-
----
-
-## Related
-
-- [Documentation index](./README.md)
-- [Angular integration guide](./angular-integration-guide.md)
-- [Angular quick start](./angular.md)
-- [In-repo Angular 16 demo](../demo/angular16/README.md)
-- [Publishing](./publishing.md)
+# Angular 16 compatibility
+
+Guide for teams on **Angular 16** who see TypeScript errors from `weg-shared-layout` in `node_modules`, or who cannot resolve subpath imports like `weg-shared-layout/weg-header`.
+
+| Doc | Use when |
+| --- | --- |
+| **[angular-integration-guide.md](./angular-integration-guide.md)** | Full integration steps |
+| **[angular.md](./angular.md)** | Quick start |
+| **[demo/angular16/README.md](../demo/angular16/README.md)** | Copy-paste Angular 16 app (npm-style imports) |
+| **This doc** | `stencil-public-runtime.d.ts` / `Mixin<const …>` errors, subpath import resolution, layout typing on TS 4.9 |
+
+---
+
+## Short answers
+
+### Is `src/types/layout-data.ts` using `type` the problem?
+
+**No.** Those definitions compile to plain `.d.ts` shapes. They do not use TypeScript 5-only syntax.
+
+The errors you see point at **`node_modules/weg-shared-layout/dist/types/stencil-public-runtime.d.ts`**. That file is **generated by Stencil** when the package is built, not authored from `layout-data.ts`.
+
+### Can we switch to `interface` or `class` instead?
+
+You can use **`interface`** in your **Angular app** for the same fields (see [Layout types in your app](#layout-types-in-your-app)). Changing the library from `type` to `interface` **does not fix** the Stencil `Mixin<const …>` errors, because Angular still type-checks (or parses) Stencil’s runtime declarations when you import from the package entry or component subpaths that pull in `components.d.ts`.
+
+**`class`** is not a good fit here: layout payloads are JSON-shaped data, not class instances.
+
+String unions (e.g. `'sign-in' | 'sign-out'`) must stay as **`type` aliases** in TypeScript; they cannot be expressed as interfaces.
+
+---
+
+## Error 1: `Mixin<const TMixins …>` / TS1139 in `stencil-public-runtime.d.ts`
+
+### What it means
+
+Stencil 4.x ships declaration files that use **TypeScript 5.0+** features, including **`const` type parameters** on generics:
+
+```ts
+export declare function Mixin<const TMixins extends readonly MixinFactory[]>(...): …;
+```
+
+If your app uses **TypeScript 4.9.x** (common on Angular 16.0–16.1 without a manual upgrade), the compiler **cannot parse** that line and reports many follow-on errors (TS1139, TS1005, etc.).
+
+This is unrelated to whether layout shapes are declared with `type`, `interface`, or `class`.
+
+### Fix A (recommended): Enable `skipLibCheck`
+
+In the Angular app’s root **`tsconfig.json`** (or `tsconfig.app.json` if that is where `compilerOptions` live):
+
+```json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+This tells TypeScript to **skip type-checking of all `.d.ts` files**, including Stencil’s. Your app source is still checked; only third-party declarations are skipped.
+
+Angular CLI **newer workspaces** often set this already. Older HeroJobs-style projects may have it **missing** — add it and rebuild.
+
+### Fix B: Use TypeScript 5.0+ (within Angular 16’s range)
+
+Angular **16.1+** supports TypeScript **`>=4.9.3` and `<5.2.0`**. Upgrade the app’s `typescript` devDependency to **5.0.x or 5.1.x** (match your exact `@angular/core` patch — see [Angular version compatibility](https://angular.dev/reference/versions)).
+
+Example:
+
+```bash
+npm i -D typescript@~5.1.6
+```
+
+Then confirm:
+
+```bash
+npx tsc --version
+```
+
+You should see **5.0+**. The `const` type parameter syntax will parse correctly even without relying only on `skipLibCheck`.
+
+### Fix C: Import layout types without the Stencil graph
+
+If you only need **`LayoutData`** (and related names) and want to avoid pulling `components.d.ts` → `stencil-public-runtime.d.ts`, import from the **types-only** subpath (package **0.0.24+**, or current main after publish):
+
+```ts
+import type { LayoutData, LayoutHeaderAuthAction } from 'weg-shared-layout/layout-data';
+```
+
+Requires **`moduleResolution`**: `"bundler"`, `"node16"`, or `"nodenext"` (see [Error 2](#error-2-cannot-find-module-weg-shared-layoutweg-header)). The `./layout-data` export is defined in this repo’s `package.json`; use a published version that includes it, or link the package locally while testing.
+
+Alternatively, keep the existing pattern from the integration guide — no import from the package at all:
+
+```ts
+import layoutFixture from 'weg-shared-layout/dummy-data.json';
+export type LayoutData = typeof layoutFixture;
+```
+
+That ties your app type to the fixture shape and never touches Stencil’s runtime `.d.ts` files.
+
+### What we are not changing in the library (for now)
+
+Replacing `type` with `interface` in `layout-data.ts` would be a **cosmetic** API change for consumers and **would not remove** `stencil-public-runtime.d.ts` from the published tarball. The durable fixes are **consumer `tsconfig`** (Fix A/B) or **types-only imports** (Fix C).
+
+---
+
+## Error 2: Cannot find module `weg-shared-layout/weg-header`
+
+Typical message:
+
+```text
+Cannot find module or type declarations for side-effect import of 'weg-shared-layout/weg-header'.
+There are types at '.../node_modules/weg-shared-layout/dist/components/weg-header.d.ts',
+but this result could not be resolved under your current 'moduleResolution' setting.
+Consider updating to 'node16', 'nodenext', or 'bundler'.
+```
+
+### What it means
+
+`weg-shared-layout` exposes components via the **`exports`** field in `package.json` (subpaths like `./weg-header`). **Classic** `"moduleResolution": "node"` (still common in Angular 16 apps) does **not** resolve those subpaths the same way, even when the `.d.ts` files exist on disk.
+
+### Fix A (recommended): Use the Stencil loader
+
+In **`src/main.ts`**, register all components **once before** `bootstrapApplication`:
+
+```ts
+import { defineCustomElements } from 'weg-shared-layout/loader';
+
+defineCustomElements();
+
+// then bootstrapApplication(...)
+```
+
+The loader path is documented in the main integration guide and avoids per-tag side-effect imports.
+
+### Fix B: Modernize `moduleResolution`
+
+In **`tsconfig.json`** (app root), set:
+
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+Angular **17+** schematics often use `bundler`. On **Angular 16**, `bundler` is supported by TypeScript 5.0+; with TS 4.9, prefer **`"node16"`** or **`"nodenext"`** if `bundler` is not available.
+
+Then side-effect imports can work:
+
+```ts
+import 'weg-shared-layout/weg-header';
+import 'weg-shared-layout/weg-footer';
+```
+
+Use **one** registration strategy: loader **or** side-effect imports, not both.
+
+### Fix C: Stay on loader only
+
+If you cannot change `moduleResolution` (team policy, older tooling), **do not** use `import 'weg-shared-layout/weg-header'`. Use **`defineCustomElements()`** from `weg-shared-layout/loader` only.
+
+---
+
+## Layout types in your app
+
+Three supported patterns (pick one):
+
+| Pattern | Example | Stencil `.d.ts` pulled? |
+| --- | --- | --- |
+| **Fixture-derived type** (default in guides) | `export type LayoutData = typeof layoutFixture` | No (only JSON + your file) |
+| **Package types subpath** | `import type { LayoutData } from 'weg-shared-layout/layout-data'` | No |
+| **Local interfaces** | Copy shapes into `layout.types.ts` | No |
+
+Example local interfaces (equivalent to package shapes; adjust if your API differs):
+
+```ts
+export interface LayoutLink {
+  label: string;
+  href?: string;
+  target?: '_blank' | '_self' | '_parent' | '_top';
+  items?: LayoutLink[];
+}
+
+export interface LayoutHeaderData {
+  logoSrc?: string;
+  menu?: LayoutLink[];
+}
+
+export type LayoutHeaderAuthAction = 'sign-in' | 'sign-out';
+
+export interface LayoutFooterSocialLink {
+  platform: 'LinkedIn' | 'Instagram' | 'TikTok' | 'YouTube';
+  href: string;
+}
+
+export interface LayoutFooterData {
+  menu?: LayoutLink[][];
+  social?: LayoutFooterSocialLink[];
+  credits?: string;
+  copyright?: string;
+}
+
+export interface LayoutData {
+  header?: Partial<LayoutHeaderData>;
+  footer?: Partial<LayoutFooterData>;
+}
+```
+
+---
+
+## Recommended `tsconfig` snippet (Angular 16 + this package)
+
+```json
+{
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+Use **`node16`** instead of **`bundler`** if you must stay on TypeScript 4.9.
+
+Pair with **`defineCustomElements()`** in `main.ts` and **`CUSTOM_ELEMENTS_SCHEMA`** on the shell component — unchanged from the main integration guide.
+
+---
+
+## Checklist for HeroJobs / similar Angular 16 apps
+
+1. Confirm TypeScript version: `npx tsc --version` (4.9 vs 5.x).
+2. Add or verify **`skipLibCheck": true`**.
+3. Set **`moduleResolution`** to `bundler` or `node16`, **or** switch to **`weg-shared-layout/loader`** only.
+4. Prefer **`export type LayoutData = typeof layoutFixture`** or **`weg-shared-layout/layout-data`** for typing — avoid `import type { LayoutData } from 'weg-shared-layout'` if you still see Stencil errors and cannot use `skipLibCheck`.
+5. Rebuild: `ng build` / CI pipeline.
+
+---
+
+## In-repo Angular 16 demo
+
+Runnable app: **[demo/angular16/README.md](../demo/angular16/README.md)** — same imports as a published npm install (`weg-shared-layout/dummy-data.json`, `weg-shared-layout/loader`); only the `package.json` dependency line differs (`file:../..` vs `^0.0.x`). Run with `npm run demo:angular16` from repo root.
+
+---
+
+## Related
+
+- [Documentation index](./README.md)
+- [Angular integration guide](./angular-integration-guide.md)
+- [Angular quick start](./angular.md)
+- [In-repo Angular 16 demo](../demo/angular16/README.md)
+- [Publishing](./publishing.md)