@public-ui/mcp 4.6.0-rc.0 → 4.6.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "metadata": {
3
- "generatedAt": "2026-11-07T05:23:24.232Z",
3
+ "generatedAt": "2026-11-12T14:19:29.502Z",
4
4
  "buildMode": "ci",
5
5
  "counts": {
6
- "total": 348,
7
- "totalDocs": 67,
8
- "totalSpecs": 53,
6
+ "total": 345,
7
+ "totalDocs": 66,
8
+ "totalSpecs": 52,
9
9
  "totalSamples": 208,
10
- "totalScenarios": 20
10
+ "totalScenarios": 19
11
11
  },
12
12
  "repo": {
13
- "commit": "7736e70f1d0f4c965cdb4340e78701923adda402",
13
+ "commit": "9a4c82a7074a914ddbcf87f5d0a647fcacee76b5",
14
14
  "branch": "release/4",
15
15
  "repoUrl": "https://github.com/public-ui/kolibri"
16
16
  }
@@ -542,15 +542,6 @@
542
542
  "code": "# Security/Sicherheit\n\n## CVE Overview\n\nSee [CVE_OVERVIEW.md](./CVE_OVERVIEW.md) for an automated overview of security vulnerabilities across all KoliBri versions.\n\n## Report security issues (EN)\n\nIf you believe you have found a security vulnerability in our project, we encourage you to let us know immediately. We will investigate all legitimate reports and do our best to fix the problem quickly.\n\nContact: [kolibri@itzbund.de](mailto:kolibri@itzbund.de)\n\n## Melden von Sicherheitsproblemen (DE)\n\nWenn Sie glauben, dass Sie eine Sicherheitslücke in unserm Projekt gefunden haben, empfehlen wir Ihnen, uns dies umgehend mitzuteilen. Wir werden alle legitimen Meldungen untersuchen und unser Bestes tun, um das Problem schnell zu beheben.\n",
543
543
  "kind": "doc"
544
544
  },
545
- {
546
- "id": "doc/SKELETON_AUDIT_REPORT",
547
- "group": "docs",
548
- "name": "SKELETON_AUDIT_REPORT",
549
- "description": "Datum: 2026-06-02 Status: 🚫 Build-Blockade erkannt (Phase 0) — Audit trotzdem vollständig durchgeführt Umfang: Alle Skeleton-bezogenen Implementierungen Effort: High (systematische Analyse aller Komponenten)",
550
- "path": "SKELETON_AUDIT_REPORT.md",
551
- "code": "# Skeleton Implementation Audit Report\n\n**Datum:** 2026-06-02 \n**Status:** 🚫 Build-Blockade erkannt (Phase 0) — Audit trotzdem vollständig durchgeführt \n**Umfang:** Alle Skeleton-bezogenen Implementierungen \n**Effort:** High (systematische Analyse aller Komponenten)\n\n---\n\n## Executive Summary\n\n### Übersicht\n\nDie Skeleton-Implementierungen im Projekt folgen einem **konsistenten Pattern**, sind aber durch mehrere **Mängel** gekennzeichnet:\n\n**Gefundene Implementierungen:**\n\n1. `_skeleton/web-components/skeleton/` — Template-Komponente (KolSkeleton)\n2. `_skeleton/web-components/click-button/` — Button-Komponente im Template\n3. `internal/functional-components/skeleton/` — Skeleton FC + Controller\n4. `internal/functional-components/click-button/` — ClickButton FC + Controller\n\n**Build-Status (Phase 0):** 🚫 **BLOCKADE**\n\n- TypeScript-Fehler in `KolFocusOptions` ↔ native `FocusOptions` (systemisch)\n- Build bricht — verhindert Validierung auf echtem Build\n\n**Konsistenz-Grade:**\n\n- ✅ **Hoch:** Controller-Pattern, Props-Handling, JSDoc-Struktur\n- 🟡 **Mittel:** Event-Propagation, Type-Safety, Error-Handling\n- 🚫 **Niedrig:** Memory-Leak-Risiken, Testing-Abdeckung, Focus-Management\n\n---\n\n## 🔍 Detaillierte Analysen\n\n### 1. KolSkeleton Component (`_skeleton/web-components/skeleton/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/components/_skeleton/web-components/skeleton/component.tsx`\n\n#### ✅ Stärken\n\n- Korrekte Stencil-Dekoration (`@Component`, `@Prop`, `@Event`, `@Method`, `@Listen`, `@Watch`)\n- JSDoc-Kommentare auf allen `@Prop`, `@Event`, `@Method` vorhanden\n- Korrektes Lifecycle-Pattern (componentWillLoad, componentDidLoad, disconnectedCallback)\n- Typsicher: `SkeletonApi` zentral definiert\n\n#### 🔴 Critical Issues\n\n**1. Fehlerhafte Focus-Delegation (Line 22)**\n\n```typescript\n@Method()\n@ctrlFocus('ctrl')\npublic async focus(options?: KolFocusOptions): Promise<void> {}\n```\n\n**Problem:**\n\n- `@ctrlFocus` Decorator wird verwendet, aber `delegateFocus` ist der aktuelle Standard (lt. memory: focus-delegation-pattern.md)\n- `KolFocusOptions` ist nicht kompatibel mit nativer `FocusOptions` → **Build-Blockade**\n- Decorator-Pattern sollte `delegateFocus('ref')` sein (wie in ClickButton)\n\n**Priorität:** 🔴 **HIGH** (Breaking + systemisch) \n**Fix:** Focus-Methode korrekt implementieren wie in `ClickButton`\n\n**2. Memory Leak durch `.bind(this)` in handleClick (Line 59)**\n\n```typescript\n@Listen('keydown')\npublic handleKeyDown(event: KeyboardEvent): void {\n // ...\n this.ctrl.handleClick(); // ✅ OK — direkt, kein .bind()\n}\n```\n\n**Positive Beobachtung:** KolSkeleton nutzt `this.ctrl.handleClick()` korrekt (kein `.bind()`).\n\n**3. Fehlende Error-Handling bei Event-Emits (Lines 84-86)**\n\n```typescript\nthis.ctrl.setOnLoadedCallback((count: number) => {\n\tthis.loaded.emit(count); // Kein try-catch\n});\n```\n\n**Problem:** Wenn `emit()` wirft → Component crashed still. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** `try-catch` um Event-Emission oder defensive Implementierung\n\n**4. Window-Listener ohne Cleanup (Line 73-76)**\n\n```typescript\n@Listen('keydown', { target: 'window' })\npublic onKeydown(event: KeyboardEvent): void {\n this.ctrl.onKeydown(event);\n}\n```\n\n**Problem:** `@Listen` mit `target: 'window'` wird automatisch von Stencil bereinigt, aber **dokumentation fehlt**. \n**Priorität:** 🟡 **MEDIUM** (Doku-Mangel) \n**Fix:** JSDoc-Kommentar: \"Auto-cleaned by Stencil\"\n\n#### 🟡 High Issues\n\n**5. Type-Assertion in SkeletonFC Props (Line 105)**\n\n```typescript\nname={this.ctrl.getRenderProp('name')} // ✅ Typsicher\n```\n\n**Status:** OK — keine Assertions.\n\n**6. Fehlende JSDoc auf State-Feldern (Lines 46-53)**\n\n```typescript\n@State()\npublic count: number = 0;\n\n@State()\npublic label: string = 'Label';\n```\n\n**Problem:** State-Felder ohne JSDoc, obwohl sie durch Events exponiert werden. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentare hinzufügen\n\n---\n\n### 2. KolClickButton Component (`_skeleton/web-components/click-button/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/components/_skeleton/web-components/click-button/component.tsx`\n\n#### ✅ Stärken\n\n- Minimal, fokussiert (Single Responsibility)\n- Korrekte `delegateFocus` Implementierung (Line 37)\n- Saubere Ref-Handling mit `createCtaRef`\n- Props-Binding korrekt\n\n#### 🚫 Critical Issues\n\n**1. Focus-Options Type-Mismatch (Line 40)**\n\n```typescript\n@Method()\n@delegateFocus('buttonRef')\npublic async focus(options?: KolFocusOptions): Promise<void> {}\n```\n\n**Problem:** Decorator erwartet `KolFocusOptions`, aber `delegateFocus` nutzt `setFocus()` welches mit `FocusOptions` arbeitet. \n**Impact:** Build-Fehler in `accordion/shadow.tsx:48` (type constraint violation)\n\n**Priorität:** 🔴 **HIGH** (systemisch) \n**Fix:** Type-Signature anpassen oder Decorator aktualisieren\n\n**2. Fehlende JSDoc auf Prop (Lines 23-26)**\n\n```typescript\n/**\n * Sets the label of the click button component.\n */\n@Prop()\npublic _label!: string;\n```\n\n**Status:** ✅ OK — JSDoc vorhanden\n\n#### 🟡 High Issues\n\n**3. onClick Handler Type-Safety (Line 57)**\n\n```typescript\nhandleClick={this.ctrl.handleClick}\n```\n\n**Problem:** `this.ctrl.handleClick` wird direkt passed — wenn Signature ändert, bricht es still. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** Arrow-Function: `handleClick={() => this.ctrl.handleClick()}`\n\n---\n\n### 3. SkeletonController (`internal/functional-components/skeleton/controller.ts`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/skeleton/controller.ts`\n\n#### 🔴 Critical Issues\n\n**1. Memory Leak: setInterval ohne Cleanup-Dokumentation (Lines 63-68)**\n\n```typescript\nprivate startLoadedEventInterval(): void {\n this.intervalId = setInterval(() => {\n this.emitLoaded(this.getState?.('count') ?? 0);\n }, 2000);\n}\n```\n\n**Problem:**\n\n- ✅ `intervalId` wird in `destroy()` gelöscht (Line 86)\n- 🚫 **Aber:** `destroy()` wird NUR in `disconnectedCallback()` aufgerufen\n- 🚫 **Große Lücke:** Wenn Component nicht destruktiv entfernt wird (z.B. `display: none`), läuft Interval endlos\n- 🚫 **Kein Dokumentation** warum `destroy()` nötig ist\n\n**Priorität:** 🔴 **CRITICAL** (Speicherleck in Production) \n**Fix:**\n\n```typescript\n// JSDoc dokumentieren\n/**\n * Startet den Loaded-Event-Interval.\n * WICHTIG: destroy() muss in disconnectedCallback() aufgerufen werden,\n * sonst läuft der Interval im Hintergrund.\n */\n```\n\n**2. Unzureichende State-Initialisierung (Lines 37-39)**\n\n```typescript\npublic toggle(): void {\n this.setState('show', !(this.getState?.('show') ?? false));\n}\n```\n\n**Problem:** `getState?.('show')` kann `undefined` sein — `?? false` ist defensiv, aber:\n\n- Default sollte in BaseController oder State-Definition sein, nicht hier\n- Keine Konsistenz mit `count` (Line 51 in component.tsx)\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** State-Defaults zentral definieren\n\n**3. Console.log statt Log.debug (Line 44)**\n\n```typescript\nconsole.log('Show should be toggled');\n```\n\n**Problem:** Inkonsistent mit anderen Zeilen die `Log.debug()` nutzen (z.B. SkeletonFC). \n**Priorität:** 🟢 **LOW** \n**Fix:** `Log.debug()` verwenden\n\n**4. Keine Error-Handling in emitLoaded (Lines 70-77)**\n\n```typescript\nprivate emitLoaded(count: number): void {\n if (this.onLoadedCallback) {\n this.onLoadedCallback(count); // Kein try-catch\n }\n}\n```\n\n**Problem:** Wenn Callback wirft → Component-State wird inkonsistent. \n**Priorität:** 🟡 **MEDIUM**\n\n#### 🟡 High Issues\n\n**5. ClickButtonController Instanz ohne State-Zugriff (Line 18)**\n\n```typescript\nthis.clickButtonCtrl = new ClickButtonController(BaseWebComponent.stateLess);\n```\n\n**Problem:** `stateLess` ist korrekt, aber:\n\n- Keine Dokumentation **warum** ClickButton stateless\n- Wenn jemand State hinzufügt → silentes Bug\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentar\n\n---\n\n### 4. ClickButtonController (`internal/functional-components/click-button/controller.ts`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/click-button/controller.ts`\n\n#### ✅ Stärken\n\n- Minimal, einfach zu verstehen\n- Korrekte Props-Handling (`watchLabel`)\n- Fokus-Delegation delegiert korrekt an `setFocus()`\n\n#### 🔴 Critical Issues\n\n**1. Memory Leak durch `.bind(this)` auf Line 32**\n\n```typescript\npublic handleClick = (): void => {\n console.log(this, this.buttonRef, 'button clicked');\n};\n```\n\n**Status:** ✅ OK — Arrow-Function (kein `.bind()`)\n\n**2. Type-Safety in setButtonRef (Line 37)**\n\n```typescript\npublic setButtonRef = (element?: HTMLButtonElement): void => {\n this.buttonRef = element;\n};\n```\n\n**Status:** ✅ OK — typsicher\n\n#### 🟡 High Issues\n\n**3. Console.log statt Log (Line 34)**\n\n```typescript\nconsole.log(this, this.buttonRef, 'button clicked');\n```\n\n**Problem:**\n\n- Nicht über Log-System\n- Logs `this` (ganze Controller-Instanz) → potenzielle Datenexposition\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** `Log.debug()` mit spezifischen Values\n\n**4. Fehlende JSDoc auf focus() (Line 22)**\n\n```typescript\npublic async focus(options?: KolFocusOptions): Promise<void> {\n return setFocus(this.buttonRef, options);\n}\n```\n\n**Problem:**\n\n- `KolFocusOptions` Type-Mismatch (systemisch)\n- Keine Dokumentation dass async ist\n\n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n### 5. SkeletonFC (`internal/functional-components/skeleton/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/skeleton/component.tsx`\n\n#### ✅ Stärken\n\n- Functional Component sauber\n- BEM-Klasse-Generierung konsistent\n- Props korrekt destructured\n\n#### 🟡 High Issues\n\n**1. Event-Propagation nicht dokumentiert (Line 15)**\n\n```typescript\nexport const SkeletonFC: FC<FunctionalComponentProps<SkeletonApi>> = (props) => {\n const { count, label, name, show, handleClick, refButton } = props;\n```\n\n**Problem:**\n\n- Event `onLoaded`, `onRendered` werden in Props passed, aber **nicht in FC genutzt**\n- Diese Events werden in KolSkeleton component direkt emittet, nicht über FC\n- **Inkonsistenz:** Props definieren Events, aber FC nutzt sie nicht\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** Dokumentation oder Props bereinigen\n\n**2. Props-Typ unsicher (Line 15)**\n\n```typescript\nFunctionalComponentProps<SkeletonApi>;\n```\n\n**Problem:** `FunctionalComponentProps<T>` ist zu allgemein — was genau wird erwartet? \n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n### 6. ClickButtonFC (`internal/functional-components/click-button/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/click-button/component.tsx`\n\n#### ✅ Stärken\n\n- Sehr sauber, minimal\n- onClick Handler korrekt\n- BEM-Klassen konsistent\n\n#### 🟡 High Issues\n\n**1. onKeyDown PreventDefault ohne Dokumentation (Line 13)**\n\n```typescript\nonKeyDown={(event) => event.preventDefault()}\n```\n\n**Problem:**\n\n- **Warum wird keydown preventDefaultet?** Keine Dokumentation\n- Das ist ungewöhnlich für ein Button-Element\n- Könnte Accessibility-Problem sein\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentar erklären warum\n\n---\n\n### 7. Testing & Snapshots\n\n#### Skeleton Snapshot Tests (`_skeleton/web-components/skeleton/snapshot.spec.tsx`)\n\n```typescript\nexecuteSnapshotTests<SkeletonSnapshotProps>(KOL_SKELETON_TAG, [KolSkeleton], [{ _name: 'Ada Lovelace' }, { _name: '' }]);\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Two snapshot variants tested\n- 🚫 **Fehlt:**\n - `show=true` vs `show=false` variant\n - `count` variations\n - Edge case: sehr lange Name\n - **State wird nicht tested** (nur Props)\n\n**Priorität:** 🟡 **MEDIUM** \n**Empfehlung:** Snapshots erweitern\n\n#### ClickButton Snapshot Tests (`_skeleton/web-components/click-button/snapshot.spec.tsx`)\n\n```typescript\nexecuteSnapshotTests<ClickButtonSnapshotProps>(KOL_CLICK_BUTTON_TAG, [KolClickButton], [{ _label: 'Click me' }, { _label: 'Submit form' }]);\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Two label variants\n- 🚫 **Fehlt:**\n - Edge cases (empty label, very long label)\n - Disabled state (if supported)\n - Focus state\n\n**Priorität:** 🟡 **MEDIUM**\n\n#### E2E Tests (`_skeleton/web-components/click-button/interaction.e2e.ts`)\n\n```typescript\ntest('should call handleClick when clicked', async ({ page }) => {\n\tconst logMessages: string[] = [];\n\tpage.on('console', (msg) => {\n\t\tlogMessages.push(msg.text());\n\t});\n\tawait page.getByRole('button', { name: 'Click' }).click();\n\texpect(logMessages.length).toBeGreaterThan(0);\n});\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Using accessibility role (correct)\n- 🚫 **Fehlt:**\n - Keyboard interaction test (Space, Enter)\n - Focus test\n - Event-Listener test (addEventListener pattern)\n - **Log assertion fragile:** `logMessages.length > 0` ist zu vage\n\n**Priorität:** 🟡 **MEDIUM** \n**Empfehlung:** E2E-Tests erweitern nach team3 Kriterien\n\n---\n\n### 8. API & Type Definitions\n\n#### SkeletonApi (`internal/functional-components/skeleton/api.tsx`)\n\n```typescript\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tListeners: { keydown: KeyboardEvent };\n\t\tMethods: { focus: (options?: KolFocusOptions) => void; toggle: () => void };\n\t\tRefs: { button: HTMLButtonElement };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n**Status:** 🟡 **Konsistent, aber Lücken**\n\n- ✅ Alle Props typsicher\n- ✅ Alle Emitters definiert\n- 🚫 **Probleme:**\n - `KolFocusOptions` ist problematisch (systemisch)\n - `Listeners` mit `keydown` ist ungewöhnlich — sollte über Events handled werden?\n - `Callbacks: click` wird nie genutzt (nur `handleClick` Arrow-Funktion)\n\n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n## 📊 Konsistenz-Analyse\n\n### Pattern Konsistenz (Web Components ↔ Functional Components)\n\n| Aspekt | KolSkeleton | KolClickButton | Standard | Status |\n| ------------------- | ------------------------------------------------------------ | --------------------- | --------------- | ----------- |\n| **Component-Dekor** | ✅ `@Component` | ✅ `@Component` | — | ✅ OK |\n| **Props** | ✅ `@Prop` + `@Watch` | ✅ `@Prop` + `@Watch` | — | ✅ OK |\n| **Events** | ✅ `@Event` | 🚫 Keine | Required | 🔴 MISMATCH |\n| **Methods** | ✅ `@Method` | ✅ `@Method` | — | ✅ OK |\n| **Listen** | ✅ `@Listen` | 🚫 Keine | Optional | 🟡 OK |\n| **State** | ✅ `@State` | 🚫 Keine | Optional | ✅ OK |\n| **JSDoc** | ✅ `@Prop/@Event` | ✅ `@Prop/@Method` | Pflicht | ✅ OK |\n| **Focus** | 🔴 `@ctrlFocus` | ✅ `@delegateFocus` | `delegateFocus` | 🔴 MISMATCH |\n| **Lifecycle** | ✅ componentWillLoad, componentDidLoad, disconnectedCallback | ✅ componentWillLoad | — | ✅ OK |\n\n**Konsistenz-Probleme:**\n\n- 🔴 **CRITICAL:** Focus-Pattern unterschiedlich (ctrlFocus vs delegateFocus)\n- 🔴 **CRITICAL:** KolSkeleton hat Events, KolClickButton nicht\n- 🚫 **Wird nicht repariert durch Template** (Template ist Guide, nicht Copy-Paste)\n\n---\n\n## 🔴 Mängelliste (priorisiert)\n\n### 🔴 CRITICAL (Blocker)\n\n#### 1. Focus-Type Mismatch (systemisch)\n\n**Files:** Alle Komponenten mit `delegateFocus` oder `ctrlFocus` \n**Issue:** `KolFocusOptions` ↔ native `FocusOptions` Inkompatibilität \n**Impact:** Build bricht \n**Fix:** Type-Alignment in `KolFocusOptions` ← `FocusOptions` \n**Effort:** High (systemisch, viele Dateien betroffen)\n\n#### 2. KolSkeleton: Fehlerhafte Focus-Decoration (Line 22)\n\n**File:** `_skeleton/web-components/skeleton/component.tsx` \n**Issue:** `@ctrlFocus('ctrl')` verwenden, aber sollte `delegateFocus('ref')` sein \n**Fix:** Pattern wie ClickButton übernehmen \n**Effort:** Low\n\n#### 3. SkeletonController: Memory Leak (Interval ohne Cleanup-Dokumentation)\n\n**File:** `internal/functional-components/skeleton/controller.ts:63-68` \n**Issue:** `setInterval()` läuft im Hintergrund wenn Component nicht destruktiv entfernt \n**Fix:** JSDoc-Dokumentation + Verify Cleanup-Path \n**Effort:** Low\n\n---\n\n### 🟡 HIGH (Quality / Safety)\n\n#### 4. Event-Emission ohne Error-Handling\n\n**Files:**\n\n- `_skeleton/web-components/skeleton/component.tsx:84`\n- `internal/functional-components/skeleton/controller.ts:74`\n\n**Issue:** `emit()` kann werfen, kein try-catch \n**Fix:** `try-catch` um Event-Emits \n**Effort:** Low\n\n#### 5. KolClickButton: onClick Handler Type-Safety (Line 57)\n\n**File:** `_skeleton/web-components/click-button/component.tsx` \n**Issue:** `handleClick={this.ctrl.handleClick}` direkt passed — keine Arrow-Func \n**Fix:** `handleClick={() => this.ctrl.handleClick()}` \n**Effort:** Trivial\n\n#### 6. Console.log statt Log-System\n\n**Files:**\n\n- `internal/functional-components/skeleton/controller.ts:44`\n- `internal/functional-components/click-button/controller.ts:34`\n\n**Issue:** Nicht über Log-System, potenzielle Datenexposition \n**Fix:** `Log.debug()` mit spezifischen Values \n**Effort:** Trivial\n\n#### 7. ClickButtonFC: onKeyDown preventDefault ohne Dokumentation (Line 13)\n\n**File:** `internal/functional-components/click-button/component.tsx` \n**Issue:** **Warum preventDefault?** Keine Dokumentation — könnte A11y-Problem sein \n**Fix:** JSDoc erklären oder entfernen wenn nicht nötig \n**Effort:** Low\n\n#### 8. Missing JSDoc on State Fields\n\n**File:** `_skeleton/web-components/skeleton/component.tsx:46-53` \n**Issue:** `@State count`, `@State label`, `@State show` ohne JSDoc \n**Fix:** JSDoc-Kommentare hinzufügen \n**Effort:** Trivial\n\n#### 9. Window-Listener Stencil Auto-Cleanup nicht dokumentiert\n\n**File:** `_skeleton/web-components/skeleton/component.tsx:73` \n**Issue:** `@Listen('keydown', { target: 'window' })` — Auto-Cleanup Stencil-Feature nicht dokumentiert \n**Fix:** JSDoc-Kommentar \n**Effort:** Trivial\n\n---\n\n### 🟢 LOW (Code Quality)\n\n#### 10. State Default-Handling inkonsistent\n\n**File:** `internal/functional-components/skeleton/controller.ts:38` \n**Issue:** `getState?.('show') ?? false` — Defaults sollten zentral sein \n**Fix:** Refactor State-Defaults in BaseController \n**Effort:** Medium (aber nice-to-have)\n\n#### 11. SkeletonFC: Event-Props nicht genutzt\n\n**File:** `internal/functional-components/skeleton/component.tsx:15-31` \n**Issue:** `onLoaded`, `onRendered` werden in Props definiert, aber nicht in FC genutzt \n**Fix:** Dokumentation oder Props-Cleanup \n**Effort:** Low\n\n#### 12. Testing: Minimal Coverage\n\n**Files:**\n\n- `_skeleton/web-components/skeleton/snapshot.spec.tsx`\n- `_skeleton/web-components/click-button/snapshot.spec.tsx`\n- `_skeleton/web-components/click-button/interaction.e2e.ts`\n\n**Issue:** Nur Happy-Path getestet, Edge Cases + State Variations fehlen \n**Fix:** Tests erweitern (show=false, count variation, empty label, keydown events) \n**Effort:** Medium\n\n#### 13. ClickButtonController: Type-Generification fragile\n\n**File:** `internal/functional-components/click-button/controller.ts` \n**Issue:** `setButtonRef` erwartet `HTMLButtonElement` — was wenn in anderen Komponenten anders? \n**Fix:** Generische Type-Parameter oder Dokumentation \n**Effort:** Low (nice-to-have)\n\n---\n\n## 📋 Empfehlungen (Implementierungs-Roadmap)\n\n### Phase 1: Kritische Fixes (BLOCKING)\n\n1. **Fix Focus-Type Mismatch (systemisch)**\n - `KolFocusOptions` → `FocusOptions` Alignment\n - Oder: Bridge-Type erstellen\n - **Effort:** High\n - **Impact:** Unblocks Build\n\n2. **Fix KolSkeleton Focus-Decoration**\n - `@ctrlFocus` → `@delegateFocus('buttonRef')`\n - **Effort:** Low\n - **Impact:** Pattern-Konsistenz\n\n3. **Document SkeletonController Memory Leak**\n - JSDoc auf `startLoadedEventInterval()`\n - Verify `destroy()` Call in `disconnectedCallback()`\n - **Effort:** Trivial\n - **Impact:** Prevents Production Issue\n\n### Phase 2: Quality Fixes (Safety)\n\n4. Event-Emission Error-Handling\n - Try-catch um `emit()` calls\n - **Effort:** Low\n\n5. Console → Log-System\n - Replace `console.log` with `Log.debug`\n - **Effort:** Trivial\n\n6. JSDoc auf State-Feldern + Window-Listener\n - **Effort:** Trivial\n\n7. ClickButtonFC: preventDefault Dokumentation\n - **Effort:** Low\n\n### Phase 3: Test Expansion\n\n8. Snapshot Tests erweitern\n - Edge Cases (empty, very long, state variations)\n - **Effort:** Medium\n\n9. E2E Tests erweitern\n - Keyboard interactions (Space, Enter, Tab)\n - Focus management\n - Event-Listener pattern testing\n - **Effort:** Medium\n\n---\n\n## 🎯 Einheitliche Implementierungs-Standards (etabliert)\n\nBasierend auf Audit sollten folgende Standards **template-übergreifend** dokumentiert werden:\n\n### Web Component Standards\n\n```typescript\n// ✅ KORREKT\n@Component({ tag: 'kol-xxx', shadow: true })\nexport class KolXxx extends BaseWebComponent<XxxApi> implements WebComponentInterface<XxxApi> {\n private readonly ctrl = new XxxController(this.stateAccess);\n\n @Prop()\n public _prop!: string;\n\n @Watch('_prop')\n public watchProp(value?: string): void {\n this.ctrl.watchProp(value);\n }\n\n @Method()\n @delegateFocus('ref') // Neu Standard\n public async focus(options?: KolFocusOptions): Promise<void> {}\n\n @Event()\n public emitted!: EventEmitter<void>;\n\n @Listen('keydown')\n public handleKeydown(event: KeyboardEvent): void {\n this.ctrl.handleKeydown(event);\n }\n\n public componentWillLoad(): void {\n this.ctrl.componentWillLoad({ prop: this._prop });\n }\n\n public componentDidLoad(): void {\n // Cleanup subscriptions, etc.\n }\n\n public disconnectedCallback(): void {\n this.ctrl.destroy(); // Wichtig für Memory Leak Prevention\n }\n\n public render(): JSX.Element {\n return <Host><XxxFC {...props} /></Host>;\n }\n}\n```\n\n### Controller Standards\n\n```typescript\n// ✅ KORREKT\nexport class XxxController extends BaseController<XxxApi> {\n\tpublic constructor(stateAccess: StateAccess<XxxApi>) {\n\t\tsuper(stateAccess, xxxPropsConfig);\n\t}\n\n\t// Props-Watching\n\tpublic watchProp(value?: string): void {\n\t\tpropConfig.apply(value, (v) => {\n\t\t\tthis.setRenderProp('prop', v);\n\t\t});\n\t}\n\n\t// Event-Emitting\n\tpublic handleClick = (): void => {\n\t\tLog.debug('click'); // Nicht console.log\n\t\t// State mutation\n\t\tthis.setState('state', newValue);\n\t\t// Event-Emitting mit try-catch\n\t\ttry {\n\t\t\tthis.onClickCallback?.();\n\t\t} catch (error) {\n\t\t\tLog.error('Click callback failed', error);\n\t\t}\n\t};\n\n\t// Lifecycle Cleanup\n\tpublic destroy(): void {\n\t\tif (this.intervalId) clearInterval(this.intervalId);\n\t\tif (this.subscription) this.subscription.unsubscribe();\n\t}\n}\n```\n\n### Type Definition Standards\n\n```typescript\n// ✅ KORREKT API Definition\nexport type XxxApi = ApiFromConfig<\n\ttypeof xxxPropsConfig,\n\t{\n\t\tCallbacks: {\n\t\t\tclick: () => void;\n\t\t};\n\t\tEmitters: {\n\t\t\temitted: void; // Vollständig typisiert\n\t\t};\n\t\tListeners: {\n\t\t\tkeydown: KeyboardEvent; // Optional, für Window-Listener\n\t\t};\n\t\tMethods: {\n\t\t\tfocus: (options?: KolFocusOptions) => Promise<void>;\n\t\t};\n\t\tRefs: {\n\t\t\tprimary: HTMLElement;\n\t\t};\n\t\tStates: {\n\t\t\tcount: number;\n\t\t};\n\t}\n>;\n```\n\n### Testing Standards\n\n**Snapshots:**\n\n- Min. 3 Varianten pro Prop\n- Edge cases (empty, very long)\n- State variations (enabled/disabled, show/hide)\n- Format: `executeSnapshotTests<Props>(TAG, [Component], [variants])`\n\n**E2E:**\n\n- Keyboard Interactions (Space, Enter, Escape, Tab)\n- Focus management\n- Event-Listener pattern (addEventListener)\n- Accessibility (ARIA)\n- Format: `test.describe` + `test.skip` mit TODO comments\n\n**JSDoc:**\n\n- Nur auf Stencil-Decorators (`@Prop`, `@Event`, `@Method`, `@State`)\n- Keine JSDoc auf nicht-Stencil Code\n- Focus-Methoden: **immer dokumentieren dass async**\n- Window-Listener: **dokumentieren Stencil auto-cleanup**\n\n---\n\n## 🚨 Build-Blockade: Focus-Type Root-Cause Analyse\n\n**Systemisches Problem (Phase 0):**\n\n```\nKolFocusOptions (kolibri custom)\n └─ type KolFocusOptions = { behavior?: 'auto' | 'smooth' }\n\nvs.\n\nFocusOptions (native browser standard)\n └─ type FocusOptions = { preventScroll?: boolean }\n```\n\n**Wo bricht es:**\n\n- `accordion/shadow.tsx:48` — `HTMLKolButtonWcElement` extends `HTMLElement`\n- Aber `HTMLElement.focus()` expects native `FocusOptions`\n- Aber `KolButton.focus()` returns `Promise<void>` mit `KolFocusOptions`\n- **Type incompatibility** → Build fails\n\n**Langfristige Lösung:**\n\n1. **Option A:** `KolFocusOptions` extends native `FocusOptions`\n\n ```typescript\n export type KolFocusOptions = FocusOptions & {\n \tbehavior?: 'auto' | 'smooth'; // Add custom behaviors\n };\n ```\n\n2. **Option B:** Separate Bridge-Type für Web Components\n\n ```typescript\n // In element-interaction.ts\n export type ComponentFocusOptions = KolFocusOptions; // Ist 'auto' | 'smooth'\n ```\n\n3. **Option C:** Focus-Methods nie native `focus()` überschreiben\n ```typescript\n // Nicht:\n // public focus(options?: FocusOptions): void { }\n // Sondern:\n // public kolFocus(options?: KolFocusOptions): Promise<void> { }\n ```\n\n**Recommendation:** Option A (least breaking)\n\n---\n\n## 📌 Summary & Next Steps\n\n### Aktueller Status\n\n- ✅ Skeleton-Pattern konsistent implementiert\n- ✅ TypeScript-Typen sauber (bis auf FocusOptions)\n- ✅ JSDoc auf Stencil-Decorators vorhanden\n- 🚫 Build-Blockade durch Focus-Type-Mismatch\n- 🚫 Memory-Leak-Risiken nicht dokumentiert\n- 🚫 Testing minimal\n\n### Sofort-Maßnahmen (High Priority)\n\n1. Focus-Type Fix (unblocks Build)\n2. SkeletonController Memory-Leak dokumentieren\n3. Event-Emission Error-Handling\n4. Console → Log-System\n\n### Mittelfristig (Phase 2)\n\n5. JSDoc-Vollständigkeit (State-Felder, Window-Listener)\n6. Test-Expansion (E2E, Snapshots)\n7. onClick Handler Binding fixen\n\n### Langfristig (Code Quality)\n\n8. State-Defaults zentral definieren\n9. Generic Type-Handling refactoren\n10. Documentation: Einheitliche Skeleton-Implementation Guidelines\n\n---\n\n**Report erstellt:** 2026-06-02 \n**Auditor:** Claude Code (team3-Framework) \n**Status:** Bereit zur Umsetzung nach Build-Fix\n",
552
- "kind": "doc"
553
- },
554
545
  {
555
546
  "id": "doc/snapshot-optimierung",
556
547
  "group": "docs",
@@ -1170,7 +1161,7 @@
1170
1161
  "kol-input-checkbox"
1171
1162
  ],
1172
1163
  "path": "packages/samples/react/src/components/drawer/scrolled.tsx",
1173
- "code": "// DrawerScrolled Class\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolButton, KolDrawer, KolInputCheckbox } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\nimport { SampleDescription } from '../SampleDescription';\nimport { DrawerRadioAlign } from './partials/align';\n\nexport const DrawerScrolled: FC = () => {\n\tconst drawerElement = useRef<HTMLKolDrawerElement>(null);\n\tconst [align, setAlign] = useState<AlignPropType>('bottom');\n\tconst [useOverflowHandling, setUseOverflowHandling] = useState(true);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample demonstrates how KolDrawer handles content that exceeds the drawer dimensions and shows the correct way to handle overflow. Use the\n\t\t\t\t\t&#34;Enable Overflow Handling&#34; toggle to see the difference between problematic behavior (content exceeding drawer bounds) and the proper solution\n\t\t\t\t\t(overflow handling within the slot content).\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"flex flex-col gap-4 mb-4\">\n\t\t\t\t<DrawerRadioAlign value={align} onChange={(_, value) => setAlign(value as AlignPropType)} />\n\t\t\t\t<KolInputCheckbox\n\t\t\t\t\t_label=\"Enable Overflow Handling (Recommended)\"\n\t\t\t\t\t_checked={useOverflowHandling}\n\t\t\t\t\t_on={{ onChange: (_, value) => setUseOverflowHandling(!!value) }}\n\t\t\t\t/>\n\t\t\t</div>\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t<KolDrawer ref={drawerElement} _label=\"Scrollable Drawer\" _level={2} _align={align}>\n\t\t\t\t\t{useOverflowHandling ? (\n\t\t\t\t\t\t// ✅ Correct approach: Outer container with fixed dimensions and overflow handling\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '90vw' : undefined,\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '90vh' : undefined,\n\t\t\t\t\t\t\t\toverflow: 'auto',\n\t\t\t\t\t\t\t\tpadding: '0',\n\t\t\t\t\t\t\t\tborder: '1px solid #999',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<div\n\t\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : undefined,\n\t\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : undefined,\n\t\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t<p>✅ Content with proper overflow handling - scrollable within drawer bounds</p>\n\t\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t\t<h3>Large Content Area (Scrollable)</h3>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContainer: {align === 'left' || align === 'right' ? '400px wide' : '90vw wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '90vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContent: {align === 'left' || align === 'right' ? '150vw wide' : '400px wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '150vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Enabled - Container has fixed size with overflow: auto\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tWith overflow handling enabled, this content scrolls properly within the drawer container. You can scroll horizontally/vertically to see all\n\t\t\t\t\t\t\t\t\t\tcontent.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t) : (\n\t\t\t\t\t\t// ❌ Problematic approach: Content directly exceeds drawer bounds\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : '400px',\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : '400px',\n\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<p>❌ Content exceeding drawer bounds - problematic behavior</p>\n\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t<h3>Large Content Area</h3>\n\t\t\t\t\t\t\t\t<p>Width: {align === 'left' || align === 'right' ? '150vw (exceeds drawer width)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>Height: {align === 'top' || align === 'bottom' ? '150vh (exceeds drawer height)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Disabled - Content extends beyond drawer boundaries\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>Without overflow handling, this content may extend beyond the drawer boundaries, causing layout issues.</p>\n\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</KolDrawer>\n\n\t\t\t\t<KolButton _label=\"Open scrollable drawer\" _on={{ onClick: () => drawerElement.current?.open() }} />\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
1164
+ "code": "// DrawerScrolled Class\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolButton, KolDrawer, KolInputCheckbox } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\nimport { SampleDescription } from '../SampleDescription';\nimport { DrawerRadioAlign } from './partials/align';\n\nexport const DrawerScrolled: FC = () => {\n\tconst drawerElement = useRef<HTMLKolDrawerElement>(null);\n\tconst [align, setAlign] = useState<AlignPropType>('bottom');\n\tconst [useOverflowHandling, setUseOverflowHandling] = useState(true);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample demonstrates how KolDrawer handles content that exceeds the drawer dimensions and shows the correct way to handle overflow. Use the\n\t\t\t\t\t&#34;Enable Overflow Handling&#34; toggle to see the difference between problematic behavior (content exceeding drawer bounds) and the proper solution\n\t\t\t\t\t(overflow handling within the slot content).\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"flex flex-col gap-4 mb-4\">\n\t\t\t\t<DrawerRadioAlign value={align} onChange={(_, value) => setAlign(value as AlignPropType)} />\n\t\t\t\t<KolInputCheckbox\n\t\t\t\t\t_label=\"Enable Overflow Handling (Recommended)\"\n\t\t\t\t\t_checked={useOverflowHandling}\n\t\t\t\t\t_on={{ onChange: (_, value) => setUseOverflowHandling(!!value) }}\n\t\t\t\t/>\n\t\t\t</div>\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t<KolDrawer ref={drawerElement} _label=\"Scrollable Drawer\" _level={2} _align={align}>\n\t\t\t\t\t{useOverflowHandling ? (\n\t\t\t\t\t\t// ✅ Correct approach: Outer container with fixed dimensions and overflow handling\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '90vw' : undefined,\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '90vh' : undefined,\n\t\t\t\t\t\t\t\toverflow: 'auto',\n\t\t\t\t\t\t\t\tpadding: '0',\n\t\t\t\t\t\t\t\tborder: '1px solid #999',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<div\n\t\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : undefined,\n\t\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : undefined,\n\t\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t<p>Content with proper overflow handling - scrollable within drawer bounds</p>\n\t\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t\t<h3>Large Content Area (Scrollable)</h3>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContainer: {align === 'left' || align === 'right' ? '400px wide' : '90vw wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '90vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContent: {align === 'left' || align === 'right' ? '150vw wide' : '400px wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '150vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Enabled - Container has fixed size with overflow: auto\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tWith overflow handling enabled, this content scrolls properly within the drawer container. You can scroll horizontally/vertically to see all\n\t\t\t\t\t\t\t\t\t\tcontent.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t) : (\n\t\t\t\t\t\t// ❌ Problematic approach: Content directly exceeds drawer bounds\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : '400px',\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : '400px',\n\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<p>❌ Content exceeding drawer bounds - problematic behavior</p>\n\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t<h3>Large Content Area</h3>\n\t\t\t\t\t\t\t\t<p>Width: {align === 'left' || align === 'right' ? '150vw (exceeds drawer width)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>Height: {align === 'top' || align === 'bottom' ? '150vh (exceeds drawer height)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Disabled - Content extends beyond drawer boundaries\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>Without overflow handling, this content may extend beyond the drawer boundaries, causing layout issues.</p>\n\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</KolDrawer>\n\n\t\t\t\t<KolButton _label=\"Open scrollable drawer\" _on={{ onClick: () => drawerElement.current?.open() }} />\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
1174
1165
  "kind": "sample"
1175
1166
  },
1176
1167
  {
@@ -2889,7 +2880,7 @@
2889
2880
  "kol-table-stateless"
2890
2881
  ],
2891
2882
  "path": "packages/samples/react/src/components/table/stateless-async-paging.tsx",
2892
- "code": "import type { KoliBriTableHeaders } from '@public-ui/components';\nimport { KolPagination, KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useEffect, useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nimport type { ComplexData } from './test-complex-data';\nimport { COMPLEX_DATA } from './test-complex-data';\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{ label: 'ID', key: 'id', textAlign: 'right', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Common name', key: 'common_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Scientific name', key: 'scientific_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Conservation status', key: 'conservation_status', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Habitat', key: 'habitat', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Diet', key: 'diet', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Geographic range', key: 'geographic_range', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t],\n\t],\n};\n\nexport const TableStatelessAsync: FC = () => {\n\tconst getAsyncData = () => new Promise<{ COMPLEX_DATA: ComplexData[] }>((resolve) => setTimeout(() => resolve({ COMPLEX_DATA }), 5000));\n\tconst loadData = () => {\n\t\tsetLoading(true);\n\t\tgetAsyncData().then((result: Awaited<ReturnType<typeof getAsyncData>>) => {\n\t\t\tsetComplexData(result.COMPLEX_DATA.slice(0, 15));\n\t\t\tsetLoading(false);\n\t\t});\n\t};\n\n\tconst [complexData, setComplexData] = useState<ComplexData[]>([]);\n\tconst [loading, setLoading] = useState<boolean>(true);\n\n\tuseEffect(() => loadData(), []);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample shows how KolTableStateless can be used async and with KolPagination. Paging and sorting are not functional here, because a backend would\n\t\t\t\t\toffer this in real life.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"async\" className=\"w-full relative\">\n\t\t\t\t<KolTableStateless\n\t\t\t\t\t_label=\"Table for demonstration purposes\"\n\t\t\t\t\t_loading={loading}\n\t\t\t\t\t_headers={HEADERS_HORIZONTAL}\n\t\t\t\t\t_data={complexData}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonSort: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t\t<KolPagination\n\t\t\t\t\t_max={200}\n\t\t\t\t\t_page={1}\n\t\t\t\t\t_siblingCount={0}\n\t\t\t\t\t_boundaryCount={2}\n\t\t\t\t\t_pageSize={15}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonChangePage: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
2883
+ "code": "import type { KoliBriTableHeaders } from '@public-ui/components';\nimport { KolPagination, KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useEffect, useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nimport type { ComplexData } from './test-complex-data';\nimport { COMPLEX_DATA } from './test-complex-data';\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{ label: 'ID', key: 'id', textAlign: 'right', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Common name', key: 'common_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Scientific name', key: 'scientific_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Conservation status', key: 'conservation_status', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Habitat', key: 'habitat', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Diet', key: 'diet', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Geographic range', key: 'geographic_range', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t],\n\t],\n};\n\nexport const TableStatelessAsync: FC = () => {\n\tconst getAsyncData = () => new Promise<{ COMPLEX_DATA: ComplexData[] }>((resolve) => setTimeout(() => resolve({ COMPLEX_DATA }), 5000));\n\tconst loadData = () => {\n\t\tsetLoading(true);\n\t\tgetAsyncData().then((result: Awaited<ReturnType<typeof getAsyncData>>) => {\n\t\t\tsetComplexData(result.COMPLEX_DATA.slice(0, 15));\n\t\t\tsetLoading(false);\n\t\t});\n\t};\n\n\tconst [complexData, setComplexData] = useState<ComplexData[]>([]);\n\tconst [loading, setLoading] = useState<boolean>(true);\n\n\tuseEffect(() => loadData(), []);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample shows how KolTableStateless can be used async and with KolPagination. Paging and sorting are not functional here, because a backend would\n\t\t\t\t\toffer this in real life.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"async\" className=\"w-full relative\">\n\t\t\t\t<KolTableStateless\n\t\t\t\t\t_label=\"Table for demonstration purposes\"\n\t\t\t\t\t_loading={loading}\n\t\t\t\t\t_headers={HEADERS_HORIZONTAL}\n\t\t\t\t\t_data={complexData}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonSort: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t\t<KolPagination\n\t\t\t\t\t_label=\"Pagination for the demonstration table\"\n\t\t\t\t\t_max={200}\n\t\t\t\t\t_page={1}\n\t\t\t\t\t_siblingCount={0}\n\t\t\t\t\t_boundaryCount={2}\n\t\t\t\t\t_pageSize={15}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonChangePage: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
2893
2884
  "kind": "sample"
2894
2885
  },
2895
2886
  {
@@ -3450,11 +3441,10 @@
3450
3441
  "kol-button",
3451
3442
  "kol-input-checkbox",
3452
3443
  "kol-input-number",
3453
- "kol-input-text",
3454
- "kol-skeleton"
3444
+ "kol-input-text"
3455
3445
  ],
3456
3446
  "path": "packages/samples/react/src/scenarios/performance-test.tsx",
3457
- "code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText, KolSkeleton } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox' | 'skeleton';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tcase 'skeleton':\n\t\t\t\treturn <KolSkeleton key={idx} _name={`skeleton-${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Render Skeletons\" _variant=\"primary\" onClick={() => handleComponentRender('skeleton')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
3447
+ "code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
3458
3448
  "kind": "scenario"
3459
3449
  },
3460
3450
  {
@@ -3546,20 +3536,6 @@
3546
3536
  "code": "import {\n\tKolButton,\n\tKolCombobox,\n\tKolInputColor,\n\tKolInputDate,\n\tKolInputEmail,\n\tKolInputFile,\n\tKolInputNumber,\n\tKolInputPassword,\n\tKolInputRange,\n\tKolInputText,\n\tKolLinkButton,\n\tKolSelect,\n\tKolSingleSelect,\n\tKolTextarea,\n} from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\nimport { useAlert } from '../hooks/useAlert';\n\nexport const SameHeightOfAllInteractiveElements: FC = () => {\n\tconst { dummyClickEventHandler } = useAlert();\n\n\tconst dummyEventHandler = {\n\t\tonClick: dummyClickEventHandler,\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tAll interactive elements, such as buttons and input fields, should have the same height to ensure a consistent and visually balanced user interface.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\t\t\t<div className=\"w-full flex flex-wrap gap-4\">\n\t\t\t\t<KolButton _icons=\"kolicon-house\" _label=\"Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolButton _hideLabel _icons=\"kolicon-house\" _label=\"Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolLinkButton _href=\"#\" _icons=\"kolicon-house\" _label=\"Link-Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolLinkButton _hideLabel _href=\"#\" _icons=\"kolicon-house\" _label=\"Link-Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolCombobox _hideLabel _icons=\"kolicon-house\" _label=\"Combobox\" _suggestions={[]} />\n\t\t\t\t<KolInputColor\n\t\t\t\t\t_hideLabel\n\t\t\t\t\t_icons={{\n\t\t\t\t\t\tleft: 'kolicon-house',\n\t\t\t\t\t}}\n\t\t\t\t\t_label=\"Input-Color\"\n\t\t\t\t/>\n\t\t\t\t<KolInputFile _hideLabel _icons=\"kolicon-house\" _label=\"Input-File\" />\n\t\t\t\t<KolInputDate _hideLabel _icons=\"kolicon-house\" _label=\"Input-Date\" />\n\t\t\t\t<KolInputEmail _hideLabel _icons=\"kolicon-house\" _label=\"Input-Email\" />\n\t\t\t\t<KolInputNumber _hideLabel _icons=\"kolicon-house\" _label=\"Input-Number\" />\n\t\t\t\t<KolInputPassword _hideLabel _icons=\"kolicon-house\" _label=\"Input-Password\" />\n\t\t\t\t<KolInputRange _hideLabel _icons=\"kolicon-house\" _label=\"Input-Range\" />\n\t\t\t\t<KolInputText _hideLabel _icons=\"kolicon-house\" _label=\"Input-Text\" />\n\t\t\t\t<KolSelect _hideLabel _icons=\"kolicon-house\" _label=\"Select\" _options={[]} />\n\t\t\t\t<KolSingleSelect _hideLabel _icons=\"kolicon-house\" _label=\"Single Select\" _options={[]} />\n\t\t\t\t<KolTextarea _hideLabel _icons=\"kolicon-house\" _label=\"Textarea\" />\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
3547
3537
  "kind": "scenario"
3548
3538
  },
3549
- {
3550
- "id": "scenario/scenarios/skeleton",
3551
- "group": "scenarios",
3552
- "name": "skeleton",
3553
- "description": "KolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein \"loaded\" Event mit dem aktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.",
3554
- "tags": [
3555
- "kol-button",
3556
- "kol-input-range",
3557
- "kol-skeleton"
3558
- ],
3559
- "path": "packages/samples/react/src/scenarios/skeleton.tsx",
3560
- "code": "import type { FC } from 'react';\nimport React, { useCallback, useRef, useState } from 'react';\n\nimport { KolButton, KolInputRange, KolSkeleton } from '@public-ui/react-v19';\nimport { SampleDescription } from '../components/SampleDescription';\n\ninterface EventLogEntry {\n\ttimestamp: string;\n\tcount: number;\n\tid: number;\n}\n\nexport const Skeleton: FC = () => {\n\tconst skeletonRef = useRef<HTMLKolSkeletonElement>(null);\n\tconst rangeRef = useRef<HTMLKolInputRangeElement>(null);\n\tconst initialCount = 3;\n\n\tconst durationFormatter = new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'millisecond', maximumFractionDigits: 1 });\n\tconst timeFormatter = new Intl.DateTimeFormat('de-DE', { hour: '2-digit', minute: '2-digit', second: '2-digit' });\n\n\tconst [count, setCount] = useState<number>(initialCount);\n\tconst [eventLog, setEventLog] = useState<EventLogEntry[]>([]);\n\tconst [lastEventTime, setLastEventTime] = useState<string>('');\n\tconst [eventCount, setEventCount] = useState<number>(0);\n\tconst [skeletonCount, setSkeletonCount] = useState<number>(20);\n\n\t// Render benchmark state\n\tconst [generation, setGeneration] = useState<number>(0);\n\tconst [renderDuration, setRenderDuration] = useState<number | null>(null);\n\tconst [isMeasuring, setIsMeasuring] = useState<boolean>(false);\n\n\t// Refs for stable values in closures (no stale closure issues)\n\tconst renderStartTimeRef = useRef<number>(0);\n\tconst expectedCountRef = useRef<number>(20);\n\tconst renderedCountRef = useRef<number>(0);\n\n\tconst handleLoaded = (event: CustomEvent<number>) => {\n\t\tconst now = new Date();\n\t\tconst timestamp = timeFormatter.format(now);\n\t\tconst newEventCount = eventCount + 1;\n\n\t\tsetCount(event.detail);\n\t\tsetLastEventTime(timestamp);\n\t\tsetEventCount(newEventCount);\n\n\t\t// Add to event log (keep only last 5 entries)\n\t\tsetEventLog((prev) => {\n\t\t\tconst newEntry: EventLogEntry = {\n\t\t\t\ttimestamp,\n\t\t\t\tcount: event.detail,\n\t\t\t\tid: newEventCount,\n\t\t\t};\n\t\t\treturn [newEntry, ...prev.slice(0, 4)];\n\t\t});\n\t};\n\n\tconst handleRendered = useCallback(() => {\n\t\trenderedCountRef.current += 1;\n\n\t\tif (renderedCountRef.current >= expectedCountRef.current) {\n\t\t\tconst duration = performance.now() - renderStartTimeRef.current;\n\t\t\tsetRenderDuration(duration);\n\t\t\tsetIsMeasuring(false);\n\t\t}\n\t}, []);\n\n\tconst handleRangeChange = (_event: Event, value: unknown) => {\n\t\tconst newValue = Number(value);\n\t\tsetSkeletonCount(newValue);\n\n\t\t// Start benchmark measurement\n\t\trenderedCountRef.current = 0;\n\t\texpectedCountRef.current = newValue;\n\t\trenderStartTimeRef.current = performance.now();\n\t\tsetRenderDuration(null);\n\t\tsetIsMeasuring(true);\n\t\tsetGeneration((prev) => prev + 1);\n\t};\n\n\tconst handleRangeBlur = () => {\n\t\t// Sicherstellen, dass der interne Wert mit dem State synchronisiert ist\n\t\tif (rangeRef.current) {\n\t\t\trangeRef.current._value = skeletonCount;\n\t\t}\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tKolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein &quot;loaded&quot; Event mit dem\n\t\t\t\t\taktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid md:grid-cols-2 gap-4 mb-4 items-center\">\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4\">\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Toggle Sichtbarkeit\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.toggle(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"primary\"\n\t\t\t\t\t/>\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Fokus auf Button\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.focus(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"secondary\"\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4 items-center\">\n\t\t\t\t\t<KolInputRange\n\t\t\t\t\t\tref={rangeRef}\n\t\t\t\t\t\t_label=\"Anzahl der Skeletons\"\n\t\t\t\t\t\t_hideLabel\n\t\t\t\t\t\t_min={1}\n\t\t\t\t\t\t_max={10000}\n\t\t\t\t\t\t_step={25}\n\t\t\t\t\t\t_value={skeletonCount}\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonChange: handleRangeChange,\n\t\t\t\t\t\t\tonBlur: handleRangeBlur,\n\t\t\t\t\t\t}}\n\t\t\t\t\t/>\n\t\t\t\t\t<span className=\"text-sm text-gray-600 whitespace-nowrap\">{skeletonCount} Skeletons</span>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* Render Benchmark */}\n\t\t\t<div className=\"mb-4 px-3 py-2 border border-gray-300 rounded bg-gray-50 flex items-center gap-4 text-sm\">\n\t\t\t\t<span className=\"font-semibold\">Benchmark:</span>\n\t\t\t\t<span className={isMeasuring ? 'text-orange-600 font-bold' : renderDuration !== null ? 'text-green-600' : 'text-gray-400'}>\n\t\t\t\t\t{isMeasuring ? 'Rendering…' : renderDuration !== null ? 'Fertig' : 'Bereit'}\n\t\t\t\t</span>\n\t\t\t\t<span className=\"font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t{renderDuration !== null ? durationFormatter.format(renderDuration) : '—'}\n\t\t\t\t</span>\n\t\t\t</div>\n\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t{Array.from({ length: skeletonCount }, (_, idx) => (\n\t\t\t\t\t<KolSkeleton\n\t\t\t\t\t\tkey={`skeleton-${generation}-${idx}`}\n\t\t\t\t\t\t_name={`Example ${idx}`}\n\t\t\t\t\t\tonLoaded={idx === 0 ? handleLoaded : undefined}\n\t\t\t\t\t\tonRendered={handleRendered}\n\t\t\t\t\t\tref={idx === 0 ? skeletonRef : undefined}\n\t\t\t\t\t/>\n\t\t\t\t))}\n\t\t\t</div>\n\n\t\t\t<div className=\"mt-6 p-4 border border-gray-300 rounded-lg bg-gray-50\">\n\t\t\t\t<h3 className=\"text-lg font-semibold mb-3\">Event Monitor</h3>\n\t\t\t\t<div className=\"grid grid-cols-1 md:grid-cols-2 gap-4\">\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Aktueller Count-Wert:</p>\n\t\t\t\t\t\t<p className=\"text-2xl font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{count}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Letztes Event:</p>\n\t\t\t\t\t\t<p className=\"text-lg\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{lastEventTime || 'Noch kein Event empfangen'}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4\">\n\t\t\t\t\t<p className=\"font-medium mb-2\">\n\t\t\t\t\t\tEvents empfangen: <span className=\"font-bold\">{eventCount}</span>\n\t\t\t\t\t</p>\n\t\t\t\t\t{eventLog.length > 0 && (\n\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t<p className=\"font-medium mb-2\">Event-Historie (letzte 5):</p>\n\t\t\t\t\t\t\t<ul className=\"text-sm space-y-1 max-h-32 overflow-y-auto\">\n\t\t\t\t\t\t\t\t{eventLog.map((entry) => (\n\t\t\t\t\t\t\t\t\t<li key={entry.id} className=\"flex justify-between items-center p-2 bg-white rounded border\">\n\t\t\t\t\t\t\t\t\t\t<span>\n\t\t\t\t\t\t\t\t\t\t\t#{entry.id}: Count = {entry.count}\n\t\t\t\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t\t\t\t\t<span className=\"text-gray-500\">{entry.timestamp}</span>\n\t\t\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t\t</ul>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4 p-3 bg-blue-50 rounded\">\n\t\t\t\t\t<p className=\"text-sm text-blue-800\">\n\t\t\t\t\t\t💡 <strong>Tipp:</strong> Die Komponente emittiert automatisch alle 2 Sekunden ein Event. Klicke auf den &quot;Click Button&quot; in der Komponente,\n\t\t\t\t\t\tum den Count-Wert zu erhöhen.\n\t\t\t\t\t</p>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
3561
- "kind": "scenario"
3562
- },
3563
3539
  {
3564
3540
  "id": "scenario/scenarios/static-form",
3565
3541
  "group": "scenarios",
@@ -3658,9 +3634,9 @@
3658
3634
  "id": "spec/ARC42-SKELETON",
3659
3635
  "group": "spec",
3660
3636
  "name": "ARC42-SKELETON",
3661
- "description": "The kol-skeleton component blueprint demonstrates how KoliBri web components can be built in a highly maintainable and decoupled fashion. It is designed as a minimal, yet complete, reference implementation for new components.",
3637
+ "description": "The skeleton architecture describes how KoliBri web components are built in a highly maintainable and decoupled fashion. It is the binding reference structure for new components.",
3662
3638
  "path": "packages/tools/mcp/node_modules/@public-ui/components/docs/ARC42-SKELETON.md",
3663
- "code": "# Skeleton Blueprint Architecture (arc42)\n\n## 1. Introduction and Goals\n\nThe `kol-skeleton` component blueprint demonstrates how KoliBri web components can be built in a highly maintainable and decoupled fashion. It is designed as a minimal, yet complete, reference implementation for new components.\n\nThe architecture is organized into **two layers** plus an optional reusable unit of logic:\n\n- **[Web Component (WC)](./web-components/skeleton/component.tsx)** — the orchestrator. It owns the Stencil lifecycle (`@Prop`/`@State`/`@Watch`/`@Method`), normalizes incoming props, manages reactive state, composes optional Behaviors, and feeds fully resolved render props to the Functional Component.\n- **[Behaviors](../../internal/functional-components/base-behavior.ts)** — optional, composable logic modules (e.g. `TooltipBehavior`). A WC may compose zero or more Behaviors. They manage their own render props but receive state access from their host WC.\n- **[Functional Component (FC)](../../internal/functional-components/skeleton/component.tsx)** — a pure, stateless renderer. It renders solely from the props handed to it and never mutates state.\n- **[Schema helpers](../../internal/props/)** — house prop types, normalization and validation helpers shared across layers.\n\nPrimary goals:\n\n- illustrate a minimal separation of concerns for long-term maintainability\n- keep the WC as the single orchestrator — no indirection layer between the custom element and the renderer\n- factor out only genuinely reusable cross-component logic into Behaviors\n- enforce consistent validation and type-safety boundaries\n- keep per-prop special treatment to a minimum — validation, defaults and hints are uniform across every component using a prop; deviations are documented exceptions with a reason, not per-component one-offs\n- document an end-to-end implementation pipeline that teams can replicate when bootstrapping new components\n\n### Blueprint Layout\n\nThe skeleton mirrors the structure recommended for production-ready components. Its web component definitions live in the regular `src/components/` folders (`click-button/`, `skeleton/`), while reusable internals (functional components, behaviors, prop schemas) reside in the shared `src/internal/` directory. Each folder holds a single responsibility to make the pipeline explicit:\n\n```text\nsrc/\n├── components/\n│ ├── click-button/ # Blueprint button web component\n│ │ ├── component.tsx # Orchestrator: props, watchers, lifecycle, render\n│ │ ├── interaction.e2e.ts # Interaction test (Playwright)\n│ │ └── snapshot.spec.tsx # Snapshot test (Jest) — co-located\n│ └── skeleton/ # Blueprint demo web component\n│ ├── component.tsx\n│ └── snapshot.spec.tsx\n└── internal/ # Shared internals\n ├── functional-components/\n │ ├── skeleton/ # Skeleton-specific logic\n │ │ ├── api.tsx # Type definitions + props config\n │ │ └── component.tsx # Stateless functional component\n │ ├── click-button/ # Reusable button FC\n │ │ ├── api.tsx\n │ │ └── component.tsx\n │ ├── tooltip/ # Tooltip behavior + FC\n │ │ ├── api.tsx\n │ │ ├── behavior.ts # TooltipBehavior\n │ │ └── component.tsx\n │ ├── bem-root-node/ # Single-root BEM wrapper FC\n │ │ └── component.tsx\n │ ├── base-behavior.ts # Shared behavior base class\n │ ├── base-web-component.ts # Shared WC base class (orchestrator helpers)\n │ └── generic-types.ts # Interface contracts\n └── props/ # Prop types, normalisation and validation\n ├── helpers/\n │ ├── factory.ts # Prop, SimpleProp, PropDefinition, apply()\n │ └── normalizers.ts # normalizeString, normalizeInteger, etc.\n ├── label.ts # LabelProp\n ├── name.ts # NameProp\n ├── show.ts # ShowProp\n └── index.ts # Re-exports\n```\n\nThis modular layout is the backbone for the architectural patterns described in the following chapters.\n\n### Usage Example\n\n```html\n<kol-skeleton _name=\"Example\"></kol-skeleton>\n```\n\n## 2. Architecture Constraints\n\n- **Stencil** is used for authoring web components with **shadow: true** only (Shadow DOM enabled for style isolation).\n- A component that embeds another component inside its own shadow DOM renders that component's **Functional Component** through an item (see §4 Embedded Components). The only element without Shadow DOM is `kol-tooltip-wc`; it stays deprecated and is kept only for DESYBRI.\n- Components must compile to framework-agnostic Custom Elements.\n- Public API properties use an underscored naming convention (e.g. `_name`) to separate external inputs from internal state.\n- Documentation and code follow the `KoliBri` casing and repository conventions.\n\n## 3. Context and Scope\n\nThe skeleton lives inside `packages/components` and does not depend on runtime frameworks. External consumers interact through HTML attributes or DOM APIs.\n\n**Shadow DOM Strategy**: KoliBri uses Web Components with Shadow DOM enabled (`shadow: true`) by default. This ensures:\n\n- **Style Isolation**: Component styles cannot leak into host page styles and vice versa\n- **Encapsulation**: Components maintain consistent appearance regardless of host environment\n- **Maintainability**: Clear boundaries prevent unintended style interactions\n\n```mermaid\nflowchart LR\n Consumer[External Consumer] --> WC[Web Component]\n WC -.-> Schema[Schema Helpers]\n WC --> Behavior[Behavior, optional]\n WC --> FC[Functional Component]\n FC --> WC\n WC --> Consumer\n```\n\nThe external consumer interacts solely with the custom element. The WC is the orchestrator: it normalizes\nincoming values (consulting the schema helpers), composes optional Behaviors, and hands the resulting render\nprops to the stateless functional component. The resulting DOM is patched back into the WC and finally\nexposed to the consumer. Each arrow corresponds to an explicit TypeScript contract, ensuring that\nintegration points are discoverable and type safe.\n\n## 4. Solution Strategy\n\nThe blueprint enforces unidirectional data flow. The WC owns the full lifecycle: it normalizes props, manages reactive state, composes Behaviors, and renders. There is no controller/aspect class between the custom element and the FC.\n\n### Web Component Layer\n\nThe WC **is** the orchestrator. It extends `BaseWebComponent<Api>`, which provides:\n\n- `propsConfig` — the concrete component declares its props config as this field. The base seeds the render-prop store with its defaults on the first access, so even a `@Watch` fired by a prop assignment before `componentWillLoad` finds the defaults (#11449).\n- `setRenderProp(key, value)` / `getRenderProp(key)` — store and read normalized render props.\n- `setRawProp(key, value)` / `getRawProp(key)` — store/read the last raw (unprocessed) `@Prop` value, useful for change detection in watchers.\n- `stateAccess` — a `{ setState, getState }` bundle passed to composed Behaviors.\n- `stateLess` — a frozen sentinel for Behaviors that use no `@State`.\n\nResponsibilities of the WC:\n\n- Declares the public API using underscored props (e.g. `_name`).\n- Owns the Stencil-specific decorators (`@Prop`, `@Event`, `@Watch`, `@State`, `@Listen`). Watchers normalize incoming values via schema helpers and store them with `setRenderProp`.\n- Manages derived/UI state on `@State` fields, updated through `setState`/`getState` for reactivity.\n- Composes optional Behaviors (e.g. `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)`).\n- Renders the FC inside a bare `<Host>` (shadow DOM). No `<Host class=\"kol-…\">` — the tag name plus Shadow DOM are sufficient.\n\nA WC has **exactly one orchestrator (itself)** plus zero or more Behaviors. A WC may compose Behaviors, never other WCs.\n\nWhen several custom elements are tag variants of **one** FC (`kol-button`, `kol-button-link` and `kol-split-button` all render `ButtonFC`; `kol-link` and `kol-link-button` all render `LinkFC`), the orchestrator implementation is shared through an abstract base class next to the element (`components/button/base.tsx` → `BaseButtonWebComponent`, `components/link/base.tsx` → `BaseLinkWebComponent`). The base extends `BaseWebComponent<Api>`, carries no Stencil decorator and holds the composed Behaviors, the event handlers, one `apply<Prop>()` method per prop and the FC render call. The concrete element keeps everything Stencil has to see in the component class: `@Component`, `@Element`, `@State`, `@Method`, every `@Prop` with a one-line `@Watch` that calls the matching `apply<Prop>()`, and the lifecycle methods, which delegate to the base (see design decision 16).\n\n```tsx\n// WC — the orchestrator (KolLink, reference implementation)\nexport class KolLink extends BaseWebComponent<LinkApi> implements WebComponentInterface<LinkApi> {\n\tprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n\tprotected readonly propsConfig: PropsConfigShape = linkPropsConfig;\n\n\t@Prop() public _href!: string;\n\n\t@Watch('_href')\n\tpublic watchHref(value?: string): void {\n\t\threfProp.apply(value, (v) => this.setRenderProp('href', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\threfProp.apply(this._href, (v) => this.setRenderProp('href', v));\n\t\tlabelWithExpertSlotProp.apply(this._label, (v) => this.setRenderProp('label', v));\n\t\t// …all other props…\n\t\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<LinkFC\n\t\t\t\t\thref={this.getRenderProp('href')}\n\t\t\t\t\tlabel={this.getRenderProp('label')}\n\t\t\t\t\trefTooltip={this.tooltipBehavior.setTooltipElementRef}\n\t\t\t\t\t// …all other render props…\n\t\t\t\t/>\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n#### Member order\n\nEvery Stencil component class lists its members in the same order:\n\n1. `static` members\n2. `@Element`\n3. each `@State`, directly followed by its `@Watch` method(s) if it has any\n4. other fields (refs, behaviors, translations, items)\n5. `constructor`\n6. each `@Prop`, directly followed by its `@Watch` method(s); a watcher of several props follows the first of them\n7. `@Event`\n8. `@Method`\n9. lifecycle methods, grouped by phase (load, update, render, disconnect): `connectedCallback`, `componentWillLoad`, `componentDidLoad`, `componentShouldUpdate`, `componentWillUpdate`, `componentDidUpdate`, `componentWillRender`, `componentDidRender`, `disconnectedCallback`. This is a declaration convention, not the order in which Stencil runs the hooks (`componentWillRender` and `componentDidRender` run before `componentDidLoad`)\n10. `@Listen`\n11. helpers and handlers: the other methods, accessors and arrow-function fields, whatever their visibility\n12. `render`\n\nProperty initializers run in declaration order. A property whose value another initializer reads therefore stays before that property, even when its group comes later (e.g. `translateFilenameText` before the `@State` `filename` of `kol-input-file`). `component-structure.spec.ts` pins the member order of all components. For every class under `src` it also checks that no initializer reads an own property declared after it, directly (`this.x`), through own getters it reads (`this.derived`) or through own methods and arrow-function properties it calls (`this.compute()`), also nested through the called bodies. Every other path is not traced, e.g. a callee that receives `this` (`new Behavior(this)`), a synchronously run callback (an IIFE, `[1].map(() => this.later)`), `call`/`apply`/`bind` and element access (`this['x']`); keep such reads behind the property they read.\n\n### Public API Contract (Migration Parity)\n\nThe public API of a web component is exactly its set of `@Prop`/`@Method` members — for KoliBri\nthe underscored props (`_href`, `_label`, …) plus the public methods (`focus()`, `click()`, …) —\n**including** their JSDoc comments, their types, their defaults and any `@deprecated` markers.\n\n**Migration rule: the public API of a migrated component must be identical to its predecessor.**\nWhen refactoring a legacy component to the skeleton architecture, the migrated WC must expose the\nsame public members, with the same types (schema aliases, not downgraded primitives), the same\ndefaults and the same documentation. It must not add, remove, rename, retype or undocumented any\npublic member. A behavioural difference behind an unchanged member is a separate, consciously\nreviewed decision — never a side effect of the migration.\n\n**The FC's props are internal, not public API.** The functional component is an internal renderer\ncontract: it may offer more (or differently typed) props than the WC exposes. The WC is the API\ngate — it decides which render props are fed from public props and which stay at their internal\ndefaults. Never derive the public API from the FC's props, and never add a public `@Prop` \"because\nthe FC has one\". Conversely, internal-only capabilities (e.g. `ariaOwns`, `customClass`, `tabIndex`\non `LinkFC`) may stay unreachable from the outside when the predecessor component did not expose\nthem either.\n\n**Why the JSDoc is part of the contract:** `stencil build --docs` generates `docs-vscode`,\n`docs-readme` and — via `generateCustomElementsJson` — the `custom-elements.json` descriptors\ndirectly from `prop.docs` / `method.docs`. A `@Prop` without a JSDoc comment silently loses\nIntelliSense and generated documentation for every adapter package. The same applies to\n`@deprecated` markers, which announce planned removals to consumers.\n\n**Compile-time enforcement:** the WC implements the schema interface from `src/schema` (e.g.\n`implements LinkProps`) **in addition to** `WebComponentInterface<Api>`. The generic\n`WebComponentInterface` alone derives its prop types from the internal prop definitions\n(primitives like `string`/`boolean`), which would allow the public types to silently drift away\nfrom the schema. The schema alias types (`HrefPropType`, `LabelWithExpertSlotPropType`,\n`AlternativeButtonLinkRolePropType`, …) are structurally identical to the internal external types,\nso both `implements` clauses can coexist. Legacy state-shape requirements of `*API` types (e.g.\n`InternalLinkAPI`'s `state` member) are replaced by the render-prop store; implement the `*Props`\ninterface instead.\n\n**Verification (mandatory before merging a migration):** extract every `@Prop`/`@Method`\ndeclaration with its preceding JSDoc block from the predecessor file (`git show <base>:<path>`)\nand from the migrated file, and diff the two member lists. Any difference is a finding that needs\nan explicit justification in the PR description.\n\nThis is enforced continuously by the contract tests in\n[`src/components/public-api/`](../src/components/public-api/contract.ts): one `<component>.spec.ts` per component folder\nextracts the `@Prop`/`@Method` members (including JSDoc, types, defaults and requiredness) from the\ncomponent sources and compares them against a pinned contract, using the helpers in `contract.ts`.\n**Pin every component before its migration** (against the legacy `shadow.tsx`) and point the pin to\n`component.tsx` in the migration PR — the pin makes any public API change fail the build, which is\nexactly the point: such a change is a breaking change and must be an explicit, reviewable edit. One\nfile per component keeps parallel migrations free of merge conflicts.\n\n### Theming Contract (Shadow DOM Structure and BEM Classes)\n\nBesides the public API, a component exposes its rendered structure to themes: the nodes of its\nshadow DOM and the BEM classes on them, including a class on the host element. Themes, our own and\nthose of consumers, select these classes. This theming contract is versioned differently from the\npublic API:\n\n| Change | Classification | Release |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------- |\n| `@Prop`/`@Method`/`@Event`/slot, their types, defaults, documentation and behaviour, exported types | breaking change | major |\n| internal DOM structure (added, removed or moved nodes) and the BEM classes the structure needs (renamed, added, removed or moved classes) | **theming breaking change** | at least minor |\n\nA theming breaking change is not treated as a hard breaking change, because a theme can be adapted\nto it largely automatically: the theme's own visual snapshots show every affected selector, and the\n[`zero-visual-delta-handoff`](../../../../../.claude/skills/zero-visual-delta-handoff/SKILL.md) skill\ntogether with `pnpm check:skeleton-selectors` drives the theme back to zero pixel differences.\n\nRules for such a change:\n\n- The pull request adapts every theme of this repository in the same change, with zero pixel\n differences in the visual review.\n- It carries the release label `release:theming`, so the change appears in the changelog under\n _Theming_, and its title or description marks it as a **theming breaking change**.\n- The description lists each affected class or node with its old and new form, so theme authors\n can adapt their selectors.\n\n### Behavior Layer\n\nA Behavior is a reusable unit of logic that lives **inside** a WC. It extends `BaseBehavior<Api>` and:\n\n- Manages its own render props (`setRenderProp`/`getRenderProp`), seeded from its own props config in the `BaseBehavior` constructor.\n- Receives `StateAccess<Api>` from its host WC — either a real bundle or `BaseWebComponent.stateLess` when it manages no `@State`.\n- Exposes watcher entry points and lifecycle hooks (`componentWillLoad`) that the WC delegates to.\n- Must never instantiate other Behaviors directly — only the WC composes them.\n\nRule of thumb: a Behavior exists only when the same logic is genuinely shared across multiple components. The sole current example is `TooltipBehavior`, composed by link, button, and similar components.\n\n```tsx\n// Inside a WC\nprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n// delegating to the behavior from a watcher\nprivate applyTooltipAlign(value?: string): void {\n\ttooltipAlignProp.apply(value, (v) => {\n\t\tthis.setRenderProp('tooltipAlign', v);\n\t\tthis.tooltipBehavior.watchAlign(v);\n\t});\n}\n```\n\nFor a Behavior that has no `@State` fields, pass `BaseWebComponent.stateLess`:\n\n```tsx\nprivate readonly someStatelessBehavior = new SomeBehavior(BaseWebComponent.stateLess);\n```\n\n### Functional Component Layer\n\nThe FC is a pure renderer. It:\n\n- Receives normalized render props, callbacks, emitters and refs from the WC.\n- Avoids any side effects or state mutation. User interactions are signalled via DOM events/callbacks back to the WC.\n- Maps props to accessible markup and wires refs for imperative access when required.\n- May call stateless utility functions (e.g. `translate()`, formatters) directly — the `Callbacks` bucket in `ComponentApi` is reserved for event-driven callbacks only, not data accessors.\n\n#### BemRootNodeFC Pattern\n\nFCs use `BemRootNodeFC` to produce a single-root BEM structure. It renders exactly one `<div>` root node (enforcing a single-root FC), accepts a typed `block` name and `modifiers`, and merges an optional forwarded `class`:\n\n```tsx\nexport const LinkFC: FC<FunctionalComponentProps<LinkApi>> = (props) => {\n\tconst { disabled, inline, hideLabel, customClass, variant } = props;\n\t// …\n\treturn (\n\t\t<BemRootNodeFC\n\t\t\tblock=\"kol-link\"\n\t\t\tclass={clsx({ [customClass]: variant.includes('custom'), [classNameFromVariant(variant, 'link')]: variant.length > 0 })}\n\t\t\tmodifiers={{\n\t\t\t\tdisabled: disabled === true,\n\t\t\t\t'hide-label': hideLabel === true,\n\t\t\t\tinline: inline === true,\n\t\t\t\tstandalone: inline === false,\n\t\t\t}}\n\t\t>\n\t\t\t<a class=\"kol-link__interactive-element\" /* … */>…</a>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\nThe `block` and `modifiers` keys are validated against `KoliBriComponentsBemSchema`, so `block=\"kol-link\"` is type-checked and `modifiers={{ disabled: true }}` only accepts registered modifier keys. The output is `<div class=\"kol-link kol-link--disabled …\">`; inner elements use plain BEM element classes (`kol-link__interactive-element`, `kol-link__text`).\n\n**Registration requirement:** before using `BemRootNodeFC block=\"kol-xxx\"`, the block must be registered in `src/schema/bem-registry.ts` in **both** places — the exported `KoliBriComponentsBemSchema` type (required for compilation) and the runtime `BEM` const (consumed by the `kolibri-cli` SCSS generator). Type-only registration compiles and renders, but silently breaks theme SCSS generation.\n\n**When not to use it:** `BemRootNodeFC` always renders a `<div>` root. For FCs whose semantic root is another element (e.g. `ClickButtonFC` renders a `<button>`), build the root manually with `bem.forBlock('kol-xxx')(modifiers)` instead — the same typed schema applies. `LinkFC` and `ButtonFC` use `BemRootNodeFC` (both have extra siblings — tooltip, description — alongside their interactive element, so the wrapper is required, not just one non-div root); `SkeletonFC` and `ClickButtonFC` use direct `bem.forBlock` calls because their FC root _is_ the single non-div interactive element.\n\n### Embedded Components (Items)\n\nWhen a component renders another component inside its own shadow DOM — the close button of an alert, the sort buttons of a table, the page size select of a pagination — it renders that component's FC directly, so its own stylesheet and the theme reach the inner `.kol-…` classes. The orchestration the embedded element would own (resolved props with the element's `@Prop` defaults, Behaviors such as the tooltip, refs, event handlers) lives in an **item**: a plain object with closures, created once per embedded instance and owned by the embedding WC.\n\n| Item | Renders |\n| ---------------------------------------------------- | -------------------------------- |\n| `createButtonItem` (`button/item.ts`) | `ButtonFC` |\n| `createLinkItem` (`link/item.ts`) | `LinkFC` |\n| `createPopoverButtonItem` (`popover-button/item.ts`) | `PopoverButtonFC` |\n| `createDialogItem` (`dialog/item.tsx`) | `DialogFC` with a card |\n| `PageSizeSelect` (`pagination/page-size-select.tsx`) | the select field of `kol-select` |\n\n- `getFcProps(…)` returns the fully resolved FC props; call it once per render.\n- `syncListeners()` runs from `componentDidRender`, `destroy()` from `disconnectedCallback`.\n- A variable number of embedded instances (one action button per table row) goes through `createItemPool` (`item-pool.ts`): each render pass takes its items by key, and `endRender()` syncs them and destroys the ones the pass no longer used.\n- The KoliBri DOM events of the embedded component are dispatched on its FC root, where the embedded element used to be, so they bubble the same way.\n\n### Schema Helper Layer\n\nWeb components receive dynamic values from HTML attributes, but internal rendering requires statically typed data. The schema helper layer bridges that gap through **graceful degradation**: attempt minimal type conversion, then validate, but never force invalid data into types.\n\nDesign principles:\n\n- **Fail gracefully**: Invalid data is ignored rather than causing errors\n- **Minimal conversion**: Only obvious transformations (string numbers → numbers)\n- **Type guarantees**: Once validated, types are guaranteed throughout the component lifecycle\n- **Single source of truth for defaults**: Default values are defined explicitly in shared prop/schema helpers and consumed by components, avoiding duplicated or drifting defaults\n- **One definition per prop**: A public prop name has one definition in `internal/props` (e.g. `disabledProp` for every `_disabled`), reused by all components. A second definition for the same render key exists only where the props of different components differ functionally (other value type, value set or documented default), where a shared factory types the value per component (callbacks, links, options), or where the meaning of the prop differs (`labelWithExpertSlotProp` beside `labelProp`: its empty string enables the expert slot); `prop-keys.spec.ts` lists these variants with their reason. Definitions that share behavior share the implementation: under different keys `createAlignPropDefinition` (`_align`, `_popoverAlign`, `_tooltipAlign`), under one key the typed factories `createCallbacksPropDefinition`, `createLinksPropDefinition` and `createOptionsPropDefinition`\n- **One explicit schema type per prop**: every prop value type is the named schema type from `src/schema/props`; as a rule, one readable PropType per functionality is shared by all of its property definitions, and prop bags, prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining a native type (see _Explicit Schema Types per Prop_)\n- **As few special treatments per prop as possible**: a prop's validation, default and hints are the same for every component using it; a component-specific deviation is a documented exception with a reason (e.g. the `LabelWithExpertSlotPropType` empty-string sentinel), never a silent one-off (see §1 Primary Goals)\n\n#### Dual-Type Props\n\nEach prop can define an **external** (Web Component API) and an **internal** (FC) type. The external type may be more permissive to support shorthand values from HTML attributes, while the internal type is always the normalized form.\n\n`Prop<K, TExternal, TInternal>` encodes both via phantom keys (`__input_${K}` carries the external type, `__propInternal__` carries the internal type). `SimpleProp<K, T>` is a shorthand when both types are identical:\n\n```typescript\n// Different external and internal types:\ntype ColorProp = Prop<'color', ColorPair | string, ColorPair>;\n// └─ Key └─ Web Component └─ FC\n\n// Same external and internal type (shorthand):\ntype NameProp = SimpleProp<'name', NamePropType>;\n// └─ Key └─ Both types\n```\n\n#### Explicit Schema Types per Prop\n\nEvery prop has exactly one named **schema type** in `src/schema/props` (e.g. `DisabledPropType` in\n`schema/props/disabled.ts`). A schema type may be structurally as simple as a native type — naming it\nis the point, not making it complex. The name is the single spelling of the type: the prop bag, the\nprop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all\nreference it, and no layer inlines a native type instead:\n\n```typescript\n// schema/props/disabled.ts — the named schema type (its structure does not change)\nexport type DisabledPropType = boolean;\n\n// internal/props/disabled.ts — the definition references the schema type\nexport type DisabledProp = SimpleProp<'disabled', DisabledPropType>;\nexport const disabledProp = createPropDefinition<DisabledProp>('disabled', false, normalizeBoolean);\n\n// components/button/component.tsx — @Prop, watcher and apply carry the schema type\n@Prop() public _disabled?: DisabledPropType = false;\n\n@Watch('_disabled')\npublic watchDisabled(value?: DisabledPropType): void {\n\tdisabledProp.apply(value, (v) => this.setRenderProp('disabled', v));\n}\n```\n\nOne caveat lives in the test toolchain, not in the compiled output: the pinned Stencil transpile does\nnot coerce attribute strings for imported type aliases\n([stenciljs/core#4663](https://github.com/stenciljs/core/issues/4663), fixed upstream), so jest sees\nthe raw attribute string on an aliased boolean/number prop while the compiled dist metadata resolves\nthe alias and the real runtime is unaffected. Tests therefore assert the normalized render props\ninstead of raw `@Prop` values; the next Stencil upgrade removes the caveat entirely.\n\nWithout the shared name, every layer spells the type its own way (`SimpleProp<'disabled', boolean>`,\n`watchDisabled(value?: boolean)`) and nothing ties the spellings together. With it, `apply`, watcher\nand FC signatures carry the domain term, drift between the layers fails the compiler instead of\nsurfacing in review, and an evolution of the schema type moves every layer at once.\n\nAs a rule, one readable PropType is defined per functionality and shared by all of its property\ndefinitions — whether there is one (`disabledProp` for `_disabled`) or several (`inputDateMaxProp`,\n`inputMaxProp`, `maxProp` and `paginationMaxProp` for `_max`, each with its own normalizer,\nvalidator or default). The shared type — not only the prop key string — is what connects the\ndefinitions of a functionality. Only in individual cases, where the meaning of the value itself\ndiffers, is a special readable PropType variant introduced — e.g. `LabelWithExpertSlotPropType`\nbeside `LabelPropType`, or the distinct `_value` types of the checkbox, radio, select, date and\nnumber inputs. `prop-keys.spec.ts` documents the variants per render key.\n\nNaming roles stay distinct: `XxxPropType` is the schema value type, `PropXxx` the schema prop bag\nand `XxxProp` the prop definition in `internal/props`.\n\nWhich variant a component uses follows its rendered markup: a `_label` that flows into the `span`\nexpert slot (`<slot name=\"expert\">`) is `LabelWithExpertSlotPropType` — the interactive elements,\nthe form-field labels and the heading (its label sits in the heading tag next to the expert slot).\nA `_label` that is a landmark name, a caption or a pure `aria-label` without an expert slot stays\n`LabelPropType` — even when the component renders unrelated expert slots elsewhere (e.g. for the\nquote content or the tree item button). The decisive test is who switches the slot: a label is a\nsentinel carrier (`''` enables the slot) only where the label value itself toggles it. A label\nrendered through a slot the component keeps open on its own — the tree item puts its label into\nthe always-open expert slot of its embedded link — carries segments but no sentinel, so it binds\n`labelLangSegmentsProp`.\n\nThis rule binds new and changed props immediately. Existing props adopt it family by family — prop\ndefinitions first, then component signatures. Where no named schema type exists yet, it is added: an\nadditive, non-breaking change, because naming a type never changes its structure.\n\n#### Label Handling Forms\n\nSix forms govern how a label value flows through the layers. They exist because the validation\nboundary and the render boundary are different places: the web component validates untyped input\n(attributes arrive as strings, adapters pass any runtime value), while a functional component\nreceives already-normalized props and never validates.\n\n1. **A functional component trusts its props.** Its prop type comes from the props config slot\n (`required` → mandatory, `optional` → partial). A guard inside a functional component is never a\n distrust of validation — it handles the documented \"not set\" state of an optional prop (the alert\n without a label renders no heading).\n2. **The \"not set\" guard is `label?.length > 0`** for optional `string | LabelSegment[] | undefined`\n labels, in JSX conditions and ternaries alike. The expression must be strictly boolean: a bare\n `label?.length &&` renders the digit `0` into the DOM when the label is the empty string.\n3. **`trimLabel(label)` is the only way to obtain a plain string** (accessible names, aria-label,\n aria-description). `trimLabel` is undefined-safe by signature (`undefined` → `''`) and the only\n place joining segment arrays — call it without `?? ''` or `|| ''`, and never apply string\n operations to a segment array directly.\n4. **`''` is the expert-slot sentinel, everywhere.** Only components with `labelWithExpertSlotProp`\n accept it; their span switches to the expert slot. Everywhere else it is an invalid value. The\n one mapping to \"not set\" lives where an empty label is legitimate input (the tooltip behavior:\n `apply(value || undefined, …)`, mapping `''` to the unset state instead of an invalid-value\n warning).\n5. **Rendered labels go through `renderLabelWithLang`** so each segment keeps its `lang` attribute\n for screen readers. A pure `aria-label` uses `trimLabel` — language segments would have no\n effect there, which is why landmark components bind `labelProp`.\n6. **Which prop definition a component binds follows its markup** (see the variant rule above);\n the forms here stay identical for all three label definitions.\n\n#### `PropDefinition<TInternal>`\n\n`PropDefinition<TInternal>` defines `normalize` (unknown → TInternal), `validate` (TInternal → boolean), `getDefaultValue()` (→ TInternal) and `apply(value, callback)`. The normalize function accepts `unknown` because HTML attributes can arrive as any type.\n\nEach `PropDefinition` provides an `apply(value, callback)` method that combines normalization, validation and fallback handling into a single call. If the value is `undefined` or `null`, the built-in default is used. Otherwise, the value is normalized and validated before being passed to the callback — ensuring callbacks only receive type-safe internal values:\n\n```typescript\nmaxProp.apply(value, (normalized) => {\n\t// normalized is number, type-safe and validated (> 0)\n\tthis.setRenderProp('max', normalized);\n});\n```\n\n##### Undefined handling, requiredness and the default contract\n\nThree rules separate the layers, so a fachliche validator never has to deal with \"not set\":\n\n1. **Requiredness is a property of the component, decided by the props config slot.** The `required`/`optional` arrays feed `ApiFromConfig` (`Props.Required`/`Props.Optional`) _and_ drive the runtime warning: `BaseWebComponent.isRequired(key)` answers from the `required` array, and the applying watcher passes it to `apply` as its third argument (`labelProp.apply(value, cb, this.isRequired('label'))`). A prop definition itself carries no requiredness — one definition serves a required prop in one component (the link's `href`) and an optional one in another (the card's) without duplication. Appliers outside a component config (items, behaviors, `resolve-props`) apply without the argument: an unset value there is a legitimate \"not set\", not a missing required value.\n2. **`apply()` intercepts `undefined` and `null` before any fachliche validation**: after the warning when `required` was passed, the built-in default is substituted and handed to the callback. `normalize` and `validate` never see a raw `undefined` from the `apply` path.\n3. **A definition with a default must accept it as a value; a definition without a default has no fallback at all.** `createPropDefinition` takes `undefined` as a deliberate \"no default\": an unset value then flows through as \"not set\" — nothing is validated, the validator only ever sees real values (e.g. `isValidLabel` checks length only). A definition that does carry a default has its fallback validated and throws on an invalid one. Either way the fachliche validation of real values stays untouched by the \"not set\" state. The factory types this guarantee: a definition created with a default exposes a non-optional `getDefaultValue(): TInternal` (`PropDefinitionWithDefault`), so callers read the fallback without assertions.\n\n#### `DependentPropDefinition<TInternal, TDeps>`\n\nSome props require context from other props to normalize or validate correctly. `createDependentPropDefinition` extends the pattern with a `TDeps` parameter passed through to both `normalize` and `validate`. Its `apply` method takes the deps object as a third argument:\n\n```typescript\nclampedNumberValueProp.apply(\n\tvalue,\n\t(normalized) => {\n\t\tthis.setRenderProp('value', normalized);\n\t},\n\t{ min: 0, max: this.getRenderProp('max') },\n);\n```\n\n#### Type Extraction\n\n`InternalOf<P>` and `ExternalOf<P>` utility types extract the correct type for each architectural layer automatically:\n\n| Layer | Type Extractor | Example (`ColorProp`) |\n| -------------------- | -------------- | --------------------- |\n| WC `@Prop` | `ExternalOf` | `ColorPair \\| string` |\n| `@Watch` handler | `ExternalOf` | `ColorPair \\| string` |\n| WC `setRenderProp` | `InternalOf` | `ColorPair` |\n| WC `getRenderProp` | `InternalOf` | `ColorPair` |\n| Functional Component | `InternalOf` | `ColorPair` |\n\n### API Definition with `PropsConfigShape` and `ApiFromConfig`\n\nComponent APIs are defined using a runtime props config object (`PropsConfigShape`) that groups prop definitions into `required` and `optional` arrays. The `ApiFromConfig<Config, Extra>` utility type derives the full `ComponentApi` type from this config, making the props config the single source of truth for both runtime behaviour (normalization, validation, defaults) and compile-time types:\n\n```ts\nexport const skeletonPropsConfig = {\n\trequired: [nameProp],\n} as const satisfies PropsConfigShape;\n\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tMethods: { focus: () => void; toggle: () => void };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n`ApiFromConfig` automatically merges the phantom prop types from the config arrays into the `Props.Required` and `Props.Optional` fields. The WC declares the same config object as its `propsConfig` field, from which the base derives the initial render-prop defaults.\n\nThe contracts between layers are formalized through TypeScript interfaces in [`generic-types.ts`](../../internal/functional-components/generic-types.ts). These generics (`WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps`) guarantee that components share a consistent shape for props, callbacks, emitters and refs.\n\n### Methods and Automatic Promise Wrapping\n\nStencil requires that all public `@Method()` decorated methods return a `Promise`. To keep API definitions concise, `ComponentApi` allows method signatures to be defined with plain return types. The `PromiseMethod<Methods>` utility type automatically wraps each method's return type in `Promise<T>` via `WebComponentInterface`:\n\n```ts\n// API definition — simple, no Promise required\nMethods: {\n focus: () => void;\n getValue: () => number;\n};\n```\n\n```ts\n// Resolved in WebComponentInterface — automatically Promise-wrapped\nfocus: () => Promise<void>;\ngetValue: () => Promise<number>;\n```\n\n`BehaviorInterface` intentionally does **not** apply `PromiseMethod` wrapping — Behaviors stay synchronous and testable, and the `async`/`Promise.resolve()` wrapping happens at the WC layer.\n\n### Event Handler Policy\n\nWC and Behavior methods follow a clear convention based on their usage pattern:\n\n- **Callbacks, event handlers, and ref setters** are declared as **arrow class properties** (`handleClick = () => { … }`). This auto-binds them to the instance, so they can be safely passed as references without `.bind(this)` or wrapper arrows.\n- **Lifecycle methods, watchers, and public API methods** (`componentWillLoad`, `watchName`, `focus`, `toggle`) remain **prototype methods** shared across all instances for memory efficiency.\n\nBecause callbacks are already arrow properties, both render patterns are valid:\n\n```tsx\n// Pattern A: Pass arrow property directly (concise)\n<ClickButtonFC handleClick={this.handleClick} refButton={this.setButtonRef} />\n\n// Pattern B: Wrap in arrow for explicit forwarding (allows intermediate logic)\n<SkeletonFC handleClick={() => this.handleClick()} refButton={(el) => this.setButtonRef(el)} />\n```\n\n#### ⚠️ Never use `.bind(this)` with `addEventListener`/`removeEventListener`\n\nArrow function properties automatically bind `this` at definition time. **Never** create new bound instances with `.bind(this)` in DOM event registration, as this causes listener accumulation and memory leaks — `addEventListener` and `removeEventListener` must receive the **exact same function reference** to match. Use an arrow property, or a ref callback that removes the old listener before adding the new one (see `src/components/popover-button/base.tsx`, `handleToggle` + `componentDidRender`/`disconnectedCallback`).\n\n### Implementation Flow\n\n1. **Initialisation** – the base seeds the render-prop store with the defaults of `propsConfig` on the first access — earliest possible point is a `@Watch` fired by a prop assignment before `componentWillLoad`. `componentWillLoad` applies the current prop snapshot, ensuring render props reflect external values before the first render. Composed Behaviors are initialized here too.\n2. **Prop updates** – `@Watch` handlers receive raw values, normalize/validate them via schema helpers, and store the result with `setRenderProp`.\n3. **Rendering** – the WC reads render props via `getRenderProp` and feeds them into the FC.\n4. **User interaction** – the FC emits DOM events / calls callbacks. The WC wires these back into its own handlers (or Behavior methods) so state transitions remain encapsulated.\n\n### Props Pattern\n\nA critical design principle is that **functional components always render using Props**, which are either:\n\n1. **Normalized and validated external props** — incoming props processed through schema helpers\n2. **Internal component state** — derived or computed values managed by the WC via `@State`\n\nThis ensures the renderer never works with raw, unvalidated data. Props must always be initialized before being passed to the FC (the seeding from `propsConfig` on the first access guarantees this).\n\n### Watcher Example\n\nIncoming props are normalized in dedicated watchers directly inside the WC:\n\n```ts\n// Prop definition (internal/props/name.ts); NamePropType is imported from schema/props/name.ts\ntype NameProp = SimpleProp<'name', NamePropType>;\nconst nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n```tsx\n// Web Component (web-components/skeleton/component.tsx)\n@Prop() public _name!: NamePropType;\n\n@Watch('_name')\npublic watchName(value?: NamePropType): void {\n\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n}\n```\n\nThe `apply()` method uses the default value built into `nameProp` when the incoming value is `undefined` or `null`.\n\n### WC State Management\n\nThe WC manages two kinds of state directly:\n\n**Normalized Props** (via `setRenderProp()`):\n\n- Stored in the render-prop map after validation\n- Updated by watchers (e.g. `watchName`)\n- Never trigger Stencil re-renders on their own\n- Retrieved via `getRenderProp(key)` for rendering\n\n**Derived/Managed State** (via `@State` + `setState()`/`getState()`):\n\n- Stored in `@State` fields on the WC\n- Used for computed or UI state (e.g. `count`, `show`, `ariaCurrent`)\n- Each `setState()` assignment triggers a Stencil re-render\n- Read back with `getState(key)`\n\n**Rule**: a prop watcher should call `setRenderProp()` to store the normalized value. Add a `setState()` call only for `@State` fields that require reactive updates. This minimizes re-renders while keeping code clear:\n\n```tsx\n@Watch('_name')\npublic watchName(value?: string): void {\n\tnameProp.apply(value, (v) => {\n\t\tthis.setRenderProp('name', v); // Store normalized prop (no re-render)\n\t\t// this.setState('name', v); // Add only if 'name' is also an @State field\n\t});\n}\n```\n\n### WC Initialization\n\nThe WC declares its props config as the `propsConfig` field; the base seeds the render-prop store from it on the first access. `componentWillLoad` applies the current prop values and initializes composed Behaviors:\n\n```tsx\n// Web Component\nprotected readonly propsConfig: PropsConfigShape = skeletonPropsConfig;\n\npublic componentWillLoad(): void {\n\tnameProp.apply(this._name, (v) => this.setRenderProp('name', v));\n\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n}\n```\n\n## 5. Building Block View\n\n```mermaid\nclassDiagram\n direction LR\n class WebComponent {\n +componentWillLoad()\n +watchName()\n +render()\n #setState(key, value)\n #getState(key)\n #setRenderProp(key, value)\n +getRenderProp(key)\n }\n class TooltipBehavior {\n +componentWillLoad(props)\n +watchLabel(value)\n +watchAlign(value)\n +getRenderProp(key)\n }\n class LinkFC {\n +render(props)\n }\n class SchemaHelpers {\n +nameProp.apply()\n +labelProp.apply()\n }\n WebComponent ..> SchemaHelpers : normalizes via\n WebComponent --> LinkFC : renders with render props\n WebComponent o--> TooltipBehavior : composes, optional\n```\n\n**Web Component** — implements `WebComponentInterface`, owns the lifecycle, normalizes props, manages reactive state, composes optional Behaviors, and renders the FC.\n\n**TooltipBehavior** — implements `BehaviorInterface`, encapsulates a single reusable concern (tooltip show/hide, listener syncing, positioning). Composed by any WC that needs it.\n\n**LinkFC** — implements `FunctionalComponentProps`, receives the render props and produces JSX without touching state.\n\n**Schema helpers** — provide deterministic data normalization and validation functions reused across all WCs.\n\n## 6. Runtime View\n\nThe following sequence demonstrates how an external update is normalized and validated before it propagates to the renderer. The WC handles normalization directly — there is no intermediate layer.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant WC as WebComponent\n participant FC as FunctionalComponent\n participant S as Schema\n U->>WC: set attribute _name=\"Alice\"\n WC->>S: nameProp.apply(\"Alice\", callback)\n S->>S: normalize(\"Alice\") → \"Alice\"\n S->>S: validate(\"Alice\") → true\n S-->>WC: callback(\"Alice\")\n WC->>WC: setRenderProp('name', \"Alice\")\n WC->>FC: render(renderProps)\n FC-->>WC: markup\n WC-->>U: updated DOM\n Note over S,WC: apply() combines normalize + validate + callback\n Note over WC,FC: renderProps contain normalized/validated data or @State\n```\n\nThis runtime view highlights how the WC normalizes and validates external values before any rendering occurs. Only after the WC updates its render props does it invoke the functional component, patch the returned markup and expose the updated DOM to the user.\n\n## 7. Deployment View\n\nThe skeleton ships as part of the `@public-ui/components` package. During build the Stencil compiler produces framework-agnostic bundles ready for distribution via npm or CDN.\n\n## 8. Cross-cutting Concepts\n\n| Concept | Description |\n| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Composition over inheritance** | WCs compose Behaviors (e.g. `TooltipBehavior`) for reusable logic rather than relying on inheritance. |\n| **Orchestrator WC** | The WC is the single orchestrator: it normalizes props, manages state, and renders. No controller/aspect class sits between the element and the FC. |\n| **BemRootNodeFC pattern** | FCs render a single root `<div>` via `BemRootNodeFC`, with a type-checked `block` and `modifiers`. Produces `<div class=\"kol-block kol-block--…\">`; inner elements use BEM element classes. |\n| **Embedded components through items** | A component that embeds another component in its own shadow DOM renders that component's FC directly; an item (`createButtonItem`, …) owns the orchestration of each embedded instance. |\n| **Declarative rendering** | Functional components are pure and stateless. |\n| **Event-driven communication** | User interaction is emitted as DOM events/callbacks rather than calling functions across layers. |\n| **Props Pattern** | Functional components exclusively receive Props that contain either normalized/validated external data or internal component state. Props must always be initialized. |\n| **Shadow DOM First** | WCs use `shadow: true`; `shadow: false` is reserved for the transitional pattern. Components that never need an element wrapper are plain FCs. |\n| **ARIA ID Uniqueness via readable nonce IDs** | Any DOM `id` referenced by ARIA attributes (e.g. `aria-controls`, `aria-labelledby`) must be unique per component instance and follow the pattern `readable-identifier-<nonce>`. Use `private readonly someId = createUniqueId('readable-identifier')` from `utils/dev.utils`. This prevents ID collisions when components are composed inside a shared DOM scope (e.g. multiple WC instances within one shadow root, or direct light-DOM usage). Shadow DOM alone is not sufficient when a shadow component renders multiple instances of an internal WC in the same shadow root. |\n| **State ownership** | The WC owns reactive state (`@State`) and render props; the FC consumes them. |\n| **Type safety** | `WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps` encode compile-time contracts between layers. |\n| **Explicit schema types** | Every prop has exactly one named schema type in `src/schema/props`; prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining native types (the stenciljs/core#4663 alias caveat is confined to the jest toolchain). |\n| **Styling boundary** | A component's `style.scss` is base styling: layout and structure only, no colors (except the black/white contrast fallback), no spacing and no dark/light color scheme (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Colors, spacing and color schemes are implemented in the theme packages. See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](../../../../../docs/BASE_STYLING_VS_THEMING_CONCEPT.md). |\n| **Watcher placement** | Attach `@Watch` only to underscored public props (e.g. `_name`); internal state fields use `@State`. |\n\n## 9. Design Decisions\n\n1. **Eliminate the Aspect layer**\n - _Previous architecture_: a separate `BaseAspect` class sat between the WC and the FC (`WC → Aspect → FC`).\n - _Reason_: the relationship was strictly 1 WC : 1 Aspect, so the Aspect was pure indirection — every watcher and render-prop access was a pass-through. The WC can manage render props directly (the base seeds them from the declared `propsConfig` field on first access; reads and writes go through `getRenderProp`/`setRenderProp` on `BaseWebComponent`). Removing the layer halves the number of classes per component, removes a constructor/`StateAccess` handoff, and keeps the data flow in one place. Only genuinely composable, cross-component logic survives as a `Behavior`.\n2. **Behaviors for genuinely shared logic only**\n - _Alternative_: also extract per-component logic into a dedicated behavior/controller.\n - _Reason_: a Behavior earns its existence only when the same logic is reused across multiple components (e.g. `TooltipBehavior`). Single-use logic stays as private methods on the WC.\n3. **Underscored public props**\n - _Alternative_: mirror external props directly without underscores.\n - _Reason_: underscores make the separation between public API and internal state explicit.\n4. **Shadow DOM enabled for web components (shadow: true)**\n - _Alternative_: allow some components to have `shadow: false`.\n - _Reason_: Shadow DOM ensures consistent style isolation and prevents CSS conflicts from host page styles, eliminating a category of hard-to-debug styling issues.\n5. **Embedded components render their FC through items**\n - _Alternative_: render a `shadow:false` element (`kol-button-wc`, …) inside the embedding component's shadow DOM, so its stylesheet reaches the inner `.kol-…` classes.\n - _Reason_: such an element duplicates the orchestrator of the public element and puts an extra node between the embedding component and the embedded block. An item keeps one orchestration per embedded instance in the embedding WC and renders the FC root in place of the element.\n6. **Centralised validation in the WC**\n - _Alternative_: perform validation scattered inside prop watchers without schema helpers.\n - _Reason_: routing all external values through `PropDefinition.apply()` keeps validation, defaults and normalization in one reusable, testable place.\n7. **Functional component rendering**\n - _Alternative_: render JSX directly inside the web component class.\n - _Reason_: a pure renderer improves testability and eliminates side effects.\n8. **Generic interface contracts**\n - _Alternative_: rely on ad-hoc typing per component.\n - _Reason_: shared interfaces keep props, callbacks, emitters and refs uniform across components, making WCs, Behaviors and renderers interchangeable.\n9. **@State for managed UI state, render props for normalized props**\n - _Pattern_: public props (e.g. `_name`) are normalized and stored as render props. UI state that is managed but not exposed as props (like `count`, `show`, `ariaCurrent`) uses `@State` to trigger reactive re-renders.\n - _Reason_: normalized props do not need `@State` — they are held as render props and accessed via `getRenderProp(key)`. This avoids unnecessary re-rendering while keeping reactive state explicit.\n10. **Host element without redundant class attribute**\n - _Alternative_: add the component name as a class attribute to `<Host>` (e.g. `<Host class=\"kol-skeleton\">`).\n - _Reason_: the tag name alone (e.g. `<kol-skeleton>`) plus Shadow DOM are sufficient for styling and identification. The BEM root class is emitted by `BemRootNodeFC` inside the FC, not on `<Host>`.\n11. **Omit unused API fields in ComponentApi definitions**\n - _Pattern_: all fields in `ComponentApi` are optional except `States` (`Props`, `Emitters`, `Methods`, `Callbacks`, `Refs`, `Listeners` — `States` is required and defaults to `Record<never, never>` via `ApiFromConfig`). Only define the fields the component actually uses. The generic type extraction in `generic-types.ts` safely defaults missing fields to empty records.\n - _Alternative_: define all fields explicitly, using empty records for unused ones.\n - _Reason_: a minimal API definition is easier to read and accurately conveys what the component does.\n12. **ARIA ID uniqueness via `createUniqueId()`**\n - _Pattern_: any `id` referenced by an ARIA relation attribute must be unique per instance. Declare stable base ids as `private readonly xId = createUniqueId('x')` and derive related ids with `createRelatedUniqueId(baseId, 'control')`.\n - _Alternative_: hardcode a static string.\n - _Reason_: Shadow DOM scopes IDs per shadow root, but a parent may render multiple instances of an internal WC in the same shadow root, colliding IDs. `createUniqueId()` is cheap and eliminates this category of bug, and also covers direct light-DOM usage.\n13. **No `data-testid` — use BEM class selectors in tests**\n - _Pattern_: do not add `data-testid` attributes. Tests select elements via their BEM class names (`page.locator('.kol-component__element')`).\n - _Alternative_: add `data-testid` and use `getByTestId()`.\n - _Reason_: BEM class names are already present, stable, and semantically tied to the component. Using them keeps production markup clean of test-only concerns.\n14. **Test co-location — all tests live next to the component**\n - _Pattern_: all test files sit directly alongside `component.tsx` — snapshot tests (`snapshot.spec.tsx`, Jest) and interaction tests (`interaction.e2e.ts`, Playwright). File names are uniform across components.\n - _Alternative_: group tests into a dedicated `test/` subdirectory.\n - _Reason_: co-located tests are easier to discover and keep related files visible side-by-side.\n15. **Public API parity during migration — the FC face is not the public face**\n - _Pattern_: a skeleton migration keeps the WC's public `@Prop`/`@Method` set byte-identical to the predecessor: same members, same schema-alias types, same defaults, same JSDoc (including `@deprecated`). The WC implements the schema `*Props` interface alongside `WebComponentInterface<Api>` so drift fails the build. Internal FC props without a public predecessor prop stay internal (fed from defaults, no public `@Prop` added).\n - _Alternative_: expose every FC prop 1:1 as a public `@Prop` and declare props with the internal primitive types.\n - _Reason_: the public API is a compatibility contract (adapters, IntelliSense, `custom-elements.json` are generated from `prop.docs`/`method.docs`). Growing it silently (e.g. link gained `_ariaOwns`, `_customClass`, `_tabIndex`, `click()`) or dropping its documentation is a breaking change disguised as a refactor. See [§4 Public API Contract](#public-api-contract-migration-parity).\n16. **Shared orchestrator base for tag variants of one FC**\n - _Pattern_: elements that render the same FC (`kol-button`/`kol-button-link`/`kol-split-button`, `kol-link`/`kol-link-button`) share an abstract, decorator-free base class next to the element (`button/base.tsx`, `link/base.tsx`) that extends `BaseWebComponent<Api>` and holds Behaviors, handlers, `apply<Prop>()` methods and the FC render call. The concrete element declares the Stencil members and delegates from its watchers and lifecycle methods.\n - _Alternative_: copy the orchestrator into every element (the state before this decision: ~350 identical lines in `component.tsx` and `wc.tsx`), or let the variants instantiate a `shadow:false` twin of the public element.\n - _Reason_: the base is not a layer between WC and FC (decision 1 stays intact) — it _is_ the WC's implementation, written once. Stencil only reads decorators and lifecycle hooks from the component class itself, so those stay there; plain methods and fields are inherited at runtime like the ones of `BaseWebComponent`. Anything that needs the host element (e.g. the form-association controller) is created from the concrete constructor after `super()`, because Stencil registers the host at the start of the component class's constructor.\n17. **DOM structure and BEM classes are a theming contract, not public API**\n - _Pattern_: a change of the internal DOM structure or of the BEM classes it needs ships in at least a minor release as a **theming breaking change**: release label `release:theming`, old and new classes listed in the pull request, all themes of this repository adapted in the same change. See [Theming Contract](#theming-contract-shadow-dom-structure-and-bem-classes).\n - _Alternative_: treat every class or node change as a breaking change that waits for the next major release.\n - _Reason_: themes can be adapted to such a change largely automatically through their own visual snapshots and the zero-visual-delta workflow. Holding back structural cleanups (single BEM root, registered classes) until a major release would keep known non-conformities alive for a long time without protecting anyone more than the changelog entry does.\n18. **Explicit schema types per prop**\n - _Pattern_: every prop's value type is the named schema type from `src/schema/props`; the prop bag, the prop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all reference that name, and no layer inlines a native type. See [Explicit Schema Types per Prop](#explicit-schema-types-per-prop).\n - _Alternative_: type prop definitions and component signatures with bare natives (`SimpleProp<'disabled', boolean>`) and keep the schema name only on the prop bag.\n - _Reason_: the type is defined once and every layer points at the same name, so drift between the layers fails the compiler instead of surfacing in review; apply and watcher signatures carry the domain term; and the prop definitions binding one render key are connected by their shared schema type, not only by the key string. Naming a type never changes its structure, so adopting it is invisible to consumers. The pinned Stencil's un-coerced attribute parsing for imported aliases (stenciljs/core#4663) is a known test-toolchain caveat, not a reason to inline natives.\n\n## 10. Quality Requirements\n\n- Maintainability: the WC is the single orchestrator, reducing the number of classes and the cost of change.\n- Reliability: schema helpers validate every external value before it mutates state.\n- Testability: the FC is a pure renderer and can be unit tested in isolation; Behaviors can be tested standalone. Snapshot tests (Jest) verify DOM output; interaction tests (Playwright) verify user-facing behaviour.\n- Performance: **optimized re-rendering** — public props are normalized and stored as render props (no re-render); only `@State` changes trigger re-renders. Stencil batches simultaneous prop/state changes into a single re-render.\n- Accessibility: follow repository-wide a11y presets and prefer `KolTooltip` over `title` attributes.\n- Security: avoid direct DOM injection; rely on typed props and validation to prevent XSS.\n\n## 11. Risks and Technical Debt\n\n- The transitional `shadow:false` WCs are temporary scaffolding; they should be removed as consumers migrate to render FCs directly.\n- WCs with many props can accumulate verbose watcher boilerplate; the `PropDefinition.apply()` pattern keeps each watcher to one line, but a component with dozens of props still produces dozens of watchers.\n- Behaviors that hold listener references must clean up in `disconnectedCallback` to avoid leaks (see the Event Handler Policy warning).\n\n## 12. Glossary\n\n| Term | Definition |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **BEM** | Block Element Modifier naming convention for CSS class names. |\n| **BemRootNodeFC** | Single-root BEM wrapper FC. Renders one `<div class=\"kol-block kol-block--…\">` from a type-checked `block` and `modifiers`. |\n| **Behavior** | Optional, composable unit of reusable logic living inside a WC; extends `BaseBehavior`. Example: `TooltipBehavior`. |\n| **Orchestrator (WC)** | The web component, which directly owns lifecycle, prop normalization, state management, Behavior composition and rendering. |\n| **Functional Component** | Pure renderer without side effects that exclusively works with Props. |\n| **Props** | Normalized and validated props or internal state passed to functional components. Must always be initialized. |\n| **Render props** | Validated, normalized prop values stored on the WC via `setRenderProp` and read via `getRenderProp` for rendering. |\n| **Schema Helper** | Utility providing `normalize` (unknown → TInternal), `validate` (TInternal → boolean) and `apply` (normalize + validate + callback) for props. |\n| **Schema Type** | Named value type of one prop in `src/schema/props` (e.g. `DisabledPropType`); the single spelling every layer references. |\n| **StateAccess** | `{ setState, getState }` bundle a WC passes to a Behavior; `BaseWebComponent.stateLess` is the no-op sentinel for stateless Behaviors. |\n| **Stencil** | Compiler for building framework-agnostic web components. |\n| **Transitional WC** | A `shadow:false` WC that renders an FC into the light DOM so legacy consumers can reach inner BEM classes; deleted once consumers migrate. |\n| **Watch Decorator** | Stencil decorator (`@Watch`) that observes prop changes. |\n",
3639
+ "code": "# Skeleton Blueprint Architecture (arc42)\n\n## 1. Introduction and Goals\n\nThe skeleton architecture describes how KoliBri web components are built in a highly maintainable and decoupled fashion. It is the binding reference structure for new components.\n\nThe architecture is organized into **two layers** plus an optional reusable unit of logic:\n\n- **Web Component (WC)** — the orchestrator. It owns the Stencil lifecycle (`@Prop`/`@State`/`@Watch`/`@Method`), normalizes incoming props, manages reactive state, composes optional Behaviors, and feeds fully resolved render props to the Functional Component.\n- **[Behaviors](../src/internal/functional-components/base-behavior.ts)** — optional, composable logic modules (e.g. `TooltipBehavior`). A WC may compose zero or more Behaviors. They manage their own render props but receive state access from their host WC.\n- **Functional Component (FC)** — a pure, stateless renderer. It renders solely from the props handed to it and never mutates state.\n- **[Schema helpers](../src/internal/props/)** — house prop types, normalization and validation helpers shared across layers.\n\nPrimary goals:\n\n- illustrate a minimal separation of concerns for long-term maintainability\n- keep the WC as the single orchestrator — no indirection layer between the custom element and the renderer\n- factor out only genuinely reusable cross-component logic into Behaviors\n- enforce consistent validation and type-safety boundaries\n- keep per-prop special treatment to a minimum — validation, defaults and hints are uniform across every component using a prop; deviations are documented exceptions with a reason, not per-component one-offs\n- document an end-to-end implementation pipeline that teams can replicate when bootstrapping new components\n\n### Blueprint Layout\n\nThe skeleton mirrors the structure recommended for production-ready components. Every web component definition lives in its own folder under `src/components/`, while reusable internals (functional components, behaviors, prop schemas) reside in the shared `src/internal/` directory. Each folder holds a single responsibility to make the pipeline explicit:\n\n```text\nsrc/\n├── components/\n│ └── <component>/ # Web component folder — one folder per component\n│ ├── component.tsx # Orchestrator: props, watchers, lifecycle, render\n│ ├── snapshot.spec.tsx # Snapshot test (Jest) — co-located\n│ └── <component>.e2e.ts # Interaction test (Playwright)\n└── internal/ # Shared internals\n ├── functional-components/\n │ ├── <component>/ # Component-specific logic\n │ │ ├── api.tsx # Type definitions + props config\n │ │ └── component.tsx # Stateless functional component\n │ ├── tooltip/ # Tooltip behavior + FC\n │ │ ├── api.tsx\n │ │ ├── behavior.ts # TooltipBehavior\n │ │ └── component.tsx\n │ ├── bem-root-node/ # Single-root BEM wrapper FC\n │ │ └── component.tsx\n │ ├── base-behavior.ts # Shared behavior base class\n │ ├── base-web-component.ts # Shared WC base class (orchestrator helpers)\n │ └── generic-types.ts # Interface contracts\n └── props/ # Prop types, normalisation and validation\n ├── helpers/\n │ ├── factory.ts # Prop, SimpleProp, PropDefinition, apply()\n │ └── normalizers.ts # normalizeString, normalizeInteger, etc.\n ├── label.ts # LabelProp\n ├── name.ts # NameProp\n ├── show.ts # ShowProp\n └── index.ts # Re-exports\n```\n\nThis modular layout is the backbone for the architectural patterns described in the following chapters.\n\n## 2. Architecture Constraints\n\n- **Stencil** is used for authoring web components with **shadow: true** only (Shadow DOM enabled for style isolation).\n- A component that embeds another component inside its own shadow DOM renders that component's **Functional Component** through an item (see §4 Embedded Components). The only element without Shadow DOM is `kol-tooltip-wc`; it stays deprecated and is kept only for DESYBRI.\n- Components must compile to framework-agnostic Custom Elements.\n- Public API properties use an underscored naming convention (e.g. `_name`) to separate external inputs from internal state.\n- Documentation and code follow the `KoliBri` casing and repository conventions.\n\n## 3. Context and Scope\n\nThe skeleton lives inside `packages/components` and does not depend on runtime frameworks. External consumers interact through HTML attributes or DOM APIs.\n\n**Shadow DOM Strategy**: KoliBri uses Web Components with Shadow DOM enabled (`shadow: true`) by default. This ensures:\n\n- **Style Isolation**: Component styles cannot leak into host page styles and vice versa\n- **Encapsulation**: Components maintain consistent appearance regardless of host environment\n- **Maintainability**: Clear boundaries prevent unintended style interactions\n\n```mermaid\nflowchart LR\n Consumer[External Consumer] --> WC[Web Component]\n WC -.-> Schema[Schema Helpers]\n WC --> Behavior[Behavior, optional]\n WC --> FC[Functional Component]\n FC --> WC\n WC --> Consumer\n```\n\nThe external consumer interacts solely with the custom element. The WC is the orchestrator: it normalizes\nincoming values (consulting the schema helpers), composes optional Behaviors, and hands the resulting render\nprops to the stateless functional component. The resulting DOM is patched back into the WC and finally\nexposed to the consumer. Each arrow corresponds to an explicit TypeScript contract, ensuring that\nintegration points are discoverable and type safe.\n\n## 4. Solution Strategy\n\nThe blueprint enforces unidirectional data flow. The WC owns the full lifecycle: it normalizes props, manages reactive state, composes Behaviors, and renders. There is no controller/aspect class between the custom element and the FC.\n\n### Web Component Layer\n\nThe WC **is** the orchestrator. It extends `BaseWebComponent<Api>`, which provides:\n\n- `propsConfig` — the concrete component declares its props config as this field. The base seeds the render-prop store with its defaults on the first access, so even a `@Watch` fired by a prop assignment before `componentWillLoad` finds the defaults (#11449).\n- `setRenderProp(key, value)` / `getRenderProp(key)` — store and read normalized render props.\n- `setRawProp(key, value)` / `getRawProp(key)` — store/read the last raw (unprocessed) `@Prop` value, useful for change detection in watchers.\n- `stateAccess` — a `{ setState, getState }` bundle passed to composed Behaviors.\n- `stateLess` — a frozen sentinel for Behaviors that use no `@State`.\n\nResponsibilities of the WC:\n\n- Declares the public API using underscored props (e.g. `_name`).\n- Owns the Stencil-specific decorators (`@Prop`, `@Event`, `@Watch`, `@State`, `@Listen`). Watchers normalize incoming values via schema helpers and store them with `setRenderProp`.\n- Manages derived/UI state on `@State` fields, updated through `setState`/`getState` for reactivity.\n- Composes optional Behaviors (e.g. `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)`).\n- Renders the FC inside a bare `<Host>` (shadow DOM). No `<Host class=\"kol-…\">` — the tag name plus Shadow DOM are sufficient.\n\nA WC has **exactly one orchestrator (itself)** plus zero or more Behaviors. A WC may compose Behaviors, never other WCs.\n\nWhen several custom elements are tag variants of **one** FC (`kol-button`, `kol-button-link` and `kol-split-button` all render `ButtonFC`; `kol-link` and `kol-link-button` all render `LinkFC`), the orchestrator implementation is shared through an abstract base class next to the element (`components/button/base.tsx` → `BaseButtonWebComponent`, `components/link/base.tsx` → `BaseLinkWebComponent`). The base extends `BaseWebComponent<Api>`, carries no Stencil decorator and holds the composed Behaviors, the event handlers, one `apply<Prop>()` method per prop and the FC render call. The concrete element keeps everything Stencil has to see in the component class: `@Component`, `@Element`, `@State`, `@Method`, every `@Prop` with a one-line `@Watch` that calls the matching `apply<Prop>()`, and the lifecycle methods, which delegate to the base (see design decision 16).\n\n```tsx\n// WC — the orchestrator (KolLink, reference implementation)\nexport class KolLink extends BaseWebComponent<LinkApi> implements WebComponentInterface<LinkApi> {\n\tprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n\tprotected readonly propsConfig: PropsConfigShape = linkPropsConfig;\n\n\t@Prop() public _href!: string;\n\n\t@Watch('_href')\n\tpublic watchHref(value?: string): void {\n\t\threfProp.apply(value, (v) => this.setRenderProp('href', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\threfProp.apply(this._href, (v) => this.setRenderProp('href', v));\n\t\tlabelWithExpertSlotProp.apply(this._label, (v) => this.setRenderProp('label', v));\n\t\t// …all other props…\n\t\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<LinkFC\n\t\t\t\t\thref={this.getRenderProp('href')}\n\t\t\t\t\tlabel={this.getRenderProp('label')}\n\t\t\t\t\trefTooltip={this.tooltipBehavior.setTooltipElementRef}\n\t\t\t\t\t// …all other render props…\n\t\t\t\t/>\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n#### Member order\n\nEvery Stencil component class lists its members in the same order:\n\n1. `static` members\n2. `@Element`\n3. each `@State`, directly followed by its `@Watch` method(s) if it has any\n4. other fields (refs, behaviors, translations, items)\n5. `constructor`\n6. each `@Prop`, directly followed by its `@Watch` method(s); a watcher of several props follows the first of them\n7. `@Event`\n8. `@Method`\n9. lifecycle methods, grouped by phase (load, update, render, disconnect): `connectedCallback`, `componentWillLoad`, `componentDidLoad`, `componentShouldUpdate`, `componentWillUpdate`, `componentDidUpdate`, `componentWillRender`, `componentDidRender`, `disconnectedCallback`. This is a declaration convention, not the order in which Stencil runs the hooks (`componentWillRender` and `componentDidRender` run before `componentDidLoad`)\n10. `@Listen`\n11. helpers and handlers: the other methods, accessors and arrow-function fields, whatever their visibility\n12. `render`\n\nProperty initializers run in declaration order. A property whose value another initializer reads therefore stays before that property, even when its group comes later (e.g. `translateFilenameText` before the `@State` `filename` of `kol-input-file`). `component-structure.spec.ts` pins the member order of all components. For every class under `src` it also checks that no initializer reads an own property declared after it, directly (`this.x`), through own getters it reads (`this.derived`) or through own methods and arrow-function properties it calls (`this.compute()`), also nested through the called bodies. Every other path is not traced, e.g. a callee that receives `this` (`new Behavior(this)`), a synchronously run callback (an IIFE, `[1].map(() => this.later)`), `call`/`apply`/`bind` and element access (`this['x']`); keep such reads behind the property they read.\n\n### Public API Contract (Migration Parity)\n\nThe public API of a web component is exactly its set of `@Prop`/`@Method` members — for KoliBri\nthe underscored props (`_href`, `_label`, …) plus the public methods (`focus()`, `click()`, …) —\n**including** their JSDoc comments, their types, their defaults and any `@deprecated` markers.\n\n**Migration rule: the public API of a migrated component must be identical to its predecessor.**\nWhen refactoring a legacy component to the skeleton architecture, the migrated WC must expose the\nsame public members, with the same types (schema aliases, not downgraded primitives), the same\ndefaults and the same documentation. It must not add, remove, rename, retype or undocumented any\npublic member. A behavioural difference behind an unchanged member is a separate, consciously\nreviewed decision — never a side effect of the migration.\n\n**The FC's props are internal, not public API.** The functional component is an internal renderer\ncontract: it may offer more (or differently typed) props than the WC exposes. The WC is the API\ngate — it decides which render props are fed from public props and which stay at their internal\ndefaults. Never derive the public API from the FC's props, and never add a public `@Prop` \"because\nthe FC has one\". Conversely, internal-only capabilities (e.g. `ariaOwns`, `customClass`, `tabIndex`\non `LinkFC`) may stay unreachable from the outside when the predecessor component did not expose\nthem either.\n\n**Why the JSDoc is part of the contract:** `stencil build --docs` generates `docs-vscode`,\n`docs-readme` and — via `generateCustomElementsJson` — the `custom-elements.json` descriptors\ndirectly from `prop.docs` / `method.docs`. A `@Prop` without a JSDoc comment silently loses\nIntelliSense and generated documentation for every adapter package. The same applies to\n`@deprecated` markers, which announce planned removals to consumers.\n\n**Compile-time enforcement:** the WC implements the schema interface from `src/schema` (e.g.\n`implements LinkProps`) **in addition to** `WebComponentInterface<Api>`. The generic\n`WebComponentInterface` alone derives its prop types from the internal prop definitions\n(primitives like `string`/`boolean`), which would allow the public types to silently drift away\nfrom the schema. The schema alias types (`HrefPropType`, `LabelWithExpertSlotPropType`,\n`AlternativeButtonLinkRolePropType`, …) are structurally identical to the internal external types,\nso both `implements` clauses can coexist. Legacy state-shape requirements of `*API` types (e.g.\n`InternalLinkAPI`'s `state` member) are replaced by the render-prop store; implement the `*Props`\ninterface instead.\n\n**Verification (mandatory before merging a migration):** extract every `@Prop`/`@Method`\ndeclaration with its preceding JSDoc block from the predecessor file (`git show <base>:<path>`)\nand from the migrated file, and diff the two member lists. Any difference is a finding that needs\nan explicit justification in the PR description.\n\nThis is enforced continuously by the contract tests in\n[`src/components/public-api/`](../src/components/public-api/contract.ts): one `<component>.spec.ts` per component folder\nextracts the `@Prop`/`@Method` members (including JSDoc, types, defaults and requiredness) from the\ncomponent sources and compares them against a pinned contract, using the helpers in `contract.ts`.\n**Pin every component before its migration** (against the legacy `shadow.tsx`) and point the pin to\n`component.tsx` in the migration PR — the pin makes any public API change fail the build, which is\nexactly the point: such a change is a breaking change and must be an explicit, reviewable edit. One\nfile per component keeps parallel migrations free of merge conflicts.\n\n### Theming Contract (Shadow DOM Structure and BEM Classes)\n\nBesides the public API, a component exposes its rendered structure to themes: the nodes of its\nshadow DOM and the BEM classes on them, including a class on the host element. Themes, our own and\nthose of consumers, select these classes. This theming contract is versioned differently from the\npublic API:\n\n| Change | Classification | Release |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------- |\n| `@Prop`/`@Method`/`@Event`/slot, their types, defaults, documentation and behaviour, exported types | breaking change | major |\n| internal DOM structure (added, removed or moved nodes) and the BEM classes the structure needs (renamed, added, removed or moved classes) | **theming breaking change** | at least minor |\n\nA theming breaking change is not treated as a hard breaking change, because a theme can be adapted\nto it largely automatically: the theme's own visual snapshots show every affected selector, and the\n[`zero-visual-delta-handoff`](../../../../../.claude/skills/zero-visual-delta-handoff/SKILL.md) skill\ntogether with `pnpm check:skeleton-selectors` drives the theme back to zero pixel differences.\n\nRules for such a change:\n\n- The pull request adapts every theme of this repository in the same change, with zero pixel\n differences in the visual review.\n- It carries the release label `release:theming`, so the change appears in the changelog under\n _Theming_, and its title or description marks it as a **theming breaking change**.\n- The description lists each affected class or node with its old and new form, so theme authors\n can adapt their selectors.\n\n### Behavior Layer\n\nA Behavior is a reusable unit of logic that lives **inside** a WC. It extends `BaseBehavior<Api>` and:\n\n- Manages its own render props (`setRenderProp`/`getRenderProp`), seeded from its own props config in the `BaseBehavior` constructor.\n- Receives `StateAccess<Api>` from its host WC — either a real bundle or `BaseWebComponent.stateLess` when it manages no `@State`.\n- Exposes watcher entry points and lifecycle hooks (`componentWillLoad`) that the WC delegates to.\n- Must never instantiate other Behaviors directly — only the WC composes them.\n\nRule of thumb: a Behavior exists only when the same logic is genuinely shared across multiple components. The sole current example is `TooltipBehavior`, composed by link, button, and similar components.\n\n```tsx\n// Inside a WC\nprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n// delegating to the behavior from a watcher\nprivate applyTooltipAlign(value?: string): void {\n\ttooltipAlignProp.apply(value, (v) => {\n\t\tthis.setRenderProp('tooltipAlign', v);\n\t\tthis.tooltipBehavior.watchAlign(v);\n\t});\n}\n```\n\nFor a Behavior that has no `@State` fields, pass `BaseWebComponent.stateLess`:\n\n```tsx\nprivate readonly someStatelessBehavior = new SomeBehavior(BaseWebComponent.stateLess);\n```\n\n### Functional Component Layer\n\nThe FC is a pure renderer. It:\n\n- Receives normalized render props, callbacks, emitters and refs from the WC.\n- Avoids any side effects or state mutation. User interactions are signalled via DOM events/callbacks back to the WC.\n- Maps props to accessible markup and wires refs for imperative access when required.\n- May call stateless utility functions (e.g. `translate()`, formatters) directly — the `Callbacks` bucket in `ComponentApi` is reserved for event-driven callbacks only, not data accessors.\n\n#### BemRootNodeFC Pattern\n\nFCs use `BemRootNodeFC` to produce a single-root BEM structure. It renders exactly one `<div>` root node (enforcing a single-root FC), accepts a typed `block` name and `modifiers`, and merges an optional forwarded `class`:\n\n```tsx\nexport const LinkFC: FC<FunctionalComponentProps<LinkApi>> = (props) => {\n\tconst { disabled, inline, hideLabel, customClass, variant } = props;\n\t// …\n\treturn (\n\t\t<BemRootNodeFC\n\t\t\tblock=\"kol-link\"\n\t\t\tclass={clsx({ [customClass]: variant.includes('custom'), [classNameFromVariant(variant, 'link')]: variant.length > 0 })}\n\t\t\tmodifiers={{\n\t\t\t\tdisabled: disabled === true,\n\t\t\t\t'hide-label': hideLabel === true,\n\t\t\t\tinline: inline === true,\n\t\t\t\tstandalone: inline === false,\n\t\t\t}}\n\t\t>\n\t\t\t<a class=\"kol-link__interactive-element\" /* … */>…</a>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\nThe `block` and `modifiers` keys are validated against `KoliBriComponentsBemSchema`, so `block=\"kol-link\"` is type-checked and `modifiers={{ disabled: true }}` only accepts registered modifier keys. The output is `<div class=\"kol-link kol-link--disabled …\">`; inner elements use plain BEM element classes (`kol-link__interactive-element`, `kol-link__text`).\n\n**Registration requirement:** before using `BemRootNodeFC block=\"kol-xxx\"`, the block must be registered in `src/schema/bem-registry.ts` in **both** places — the exported `KoliBriComponentsBemSchema` type (required for compilation) and the runtime `BEM` const (consumed by the `kolibri-cli` SCSS generator). Type-only registration compiles and renders, but silently breaks theme SCSS generation.\n\n**When not to use it:** `BemRootNodeFC` always renders a `<div>` root. For FCs whose semantic root is another element (e.g. `ClickButtonFC` renders a `<button>`), build the root manually with `bem.forBlock('kol-xxx')(modifiers)` instead — the same typed schema applies. `LinkFC` and `ButtonFC` use `BemRootNodeFC` (both have extra siblings — tooltip, description — alongside their interactive element, so the wrapper is required, not just one non-div root); `SkeletonFC` and `ClickButtonFC` use direct `bem.forBlock` calls because their FC root _is_ the single non-div interactive element.\n\n### Embedded Components (Items)\n\nWhen a component renders another component inside its own shadow DOM — the close button of an alert, the sort buttons of a table, the page size select of a pagination — it renders that component's FC directly, so its own stylesheet and the theme reach the inner `.kol-…` classes. The orchestration the embedded element would own (resolved props with the element's `@Prop` defaults, Behaviors such as the tooltip, refs, event handlers) lives in an **item**: a plain object with closures, created once per embedded instance and owned by the embedding WC.\n\n| Item | Renders |\n| ---------------------------------------------------- | -------------------------------- |\n| `createButtonItem` (`button/item.ts`) | `ButtonFC` |\n| `createLinkItem` (`link/item.ts`) | `LinkFC` |\n| `createPopoverButtonItem` (`popover-button/item.ts`) | `PopoverButtonFC` |\n| `createDialogItem` (`dialog/item.tsx`) | `DialogFC` with a card |\n| `PageSizeSelect` (`pagination/page-size-select.tsx`) | the select field of `kol-select` |\n\n- `getFcProps(…)` returns the fully resolved FC props; call it once per render.\n- `syncListeners()` runs from `componentDidRender`, `destroy()` from `disconnectedCallback`.\n- A variable number of embedded instances (one action button per table row) goes through `createItemPool` (`item-pool.ts`): each render pass takes its items by key, and `endRender()` syncs them and destroys the ones the pass no longer used.\n- The KoliBri DOM events of the embedded component are dispatched on its FC root, where the embedded element used to be, so they bubble the same way.\n\n### Schema Helper Layer\n\nWeb components receive dynamic values from HTML attributes, but internal rendering requires statically typed data. The schema helper layer bridges that gap through **graceful degradation**: attempt minimal type conversion, then validate, but never force invalid data into types.\n\nDesign principles:\n\n- **Fail gracefully**: Invalid data is ignored rather than causing errors\n- **Minimal conversion**: Only obvious transformations (string numbers → numbers)\n- **Type guarantees**: Once validated, types are guaranteed throughout the component lifecycle\n- **Single source of truth for defaults**: Default values are defined explicitly in shared prop/schema helpers and consumed by components, avoiding duplicated or drifting defaults\n- **One definition per prop**: A public prop name has one definition in `internal/props` (e.g. `disabledProp` for every `_disabled`), reused by all components. A second definition for the same render key exists only where the props of different components differ functionally (other value type, value set or documented default), where a shared factory types the value per component (callbacks, links, options), or where the meaning of the prop differs (`labelWithExpertSlotProp` beside `labelProp`: its empty string enables the expert slot); `prop-keys.spec.ts` lists these variants with their reason. Definitions that share behavior share the implementation: under different keys `createAlignPropDefinition` (`_align`, `_popoverAlign`, `_tooltipAlign`), under one key the typed factories `createCallbacksPropDefinition`, `createLinksPropDefinition` and `createOptionsPropDefinition`\n- **One explicit schema type per prop**: every prop value type is the named schema type from `src/schema/props`; as a rule, one readable PropType per functionality is shared by all of its property definitions, and prop bags, prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining a native type (see _Explicit Schema Types per Prop_)\n- **As few special treatments per prop as possible**: a prop's validation, default and hints are the same for every component using it; a component-specific deviation is a documented exception with a reason (e.g. the `LabelWithExpertSlotPropType` empty-string sentinel), never a silent one-off (see §1 Primary Goals)\n\n#### Dual-Type Props\n\nEach prop can define an **external** (Web Component API) and an **internal** (FC) type. The external type may be more permissive to support shorthand values from HTML attributes, while the internal type is always the normalized form.\n\n`Prop<K, TExternal, TInternal>` encodes both via phantom keys (`__input_${K}` carries the external type, `__propInternal__` carries the internal type). `SimpleProp<K, T>` is a shorthand when both types are identical:\n\n```typescript\n// Different external and internal types:\ntype ColorProp = Prop<'color', ColorPair | string, ColorPair>;\n// └─ Key └─ Web Component └─ FC\n\n// Same external and internal type (shorthand):\ntype NameProp = SimpleProp<'name', NamePropType>;\n// └─ Key └─ Both types\n```\n\n#### Explicit Schema Types per Prop\n\nEvery prop has exactly one named **schema type** in `src/schema/props` (e.g. `DisabledPropType` in\n`schema/props/disabled.ts`). A schema type may be structurally as simple as a native type — naming it\nis the point, not making it complex. The name is the single spelling of the type: the prop bag, the\nprop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all\nreference it, and no layer inlines a native type instead:\n\n```typescript\n// schema/props/disabled.ts — the named schema type (its structure does not change)\nexport type DisabledPropType = boolean;\n\n// internal/props/disabled.ts — the definition references the schema type\nexport type DisabledProp = SimpleProp<'disabled', DisabledPropType>;\nexport const disabledProp = createPropDefinition<DisabledProp>('disabled', false, normalizeBoolean);\n\n// components/button/component.tsx — @Prop, watcher and apply carry the schema type\n@Prop() public _disabled?: DisabledPropType = false;\n\n@Watch('_disabled')\npublic watchDisabled(value?: DisabledPropType): void {\n\tdisabledProp.apply(value, (v) => this.setRenderProp('disabled', v));\n}\n```\n\nOne caveat lives in the test toolchain, not in the compiled output: the pinned Stencil transpile does\nnot coerce attribute strings for imported type aliases\n([stenciljs/core#4663](https://github.com/stenciljs/core/issues/4663), fixed upstream), so jest sees\nthe raw attribute string on an aliased boolean/number prop while the compiled dist metadata resolves\nthe alias and the real runtime is unaffected. Tests therefore assert the normalized render props\ninstead of raw `@Prop` values; the next Stencil upgrade removes the caveat entirely.\n\nWithout the shared name, every layer spells the type its own way (`SimpleProp<'disabled', boolean>`,\n`watchDisabled(value?: boolean)`) and nothing ties the spellings together. With it, `apply`, watcher\nand FC signatures carry the domain term, drift between the layers fails the compiler instead of\nsurfacing in review, and an evolution of the schema type moves every layer at once.\n\nAs a rule, one readable PropType is defined per functionality and shared by all of its property\ndefinitions — whether there is one (`disabledProp` for `_disabled`) or several (`inputDateMaxProp`,\n`inputMaxProp`, `maxProp` and `paginationMaxProp` for `_max`, each with its own normalizer,\nvalidator or default). The shared type — not only the prop key string — is what connects the\ndefinitions of a functionality. Only in individual cases, where the meaning of the value itself\ndiffers, is a special readable PropType variant introduced — e.g. `LabelWithExpertSlotPropType`\nbeside `LabelPropType`, or the distinct `_value` types of the checkbox, radio, select, date and\nnumber inputs. `prop-keys.spec.ts` documents the variants per render key.\n\nNaming roles stay distinct: `XxxPropType` is the schema value type, `PropXxx` the schema prop bag\nand `XxxProp` the prop definition in `internal/props`.\n\nWhich variant a component uses follows its rendered markup: a `_label` that flows into the `span`\nexpert slot (`<slot name=\"expert\">`) is `LabelWithExpertSlotPropType` — the interactive elements,\nthe form-field labels and the heading (its label sits in the heading tag next to the expert slot).\nA `_label` that is a landmark name, a caption or a pure `aria-label` without an expert slot stays\n`LabelPropType` — even when the component renders unrelated expert slots elsewhere (e.g. for the\nquote content or the tree item button). The decisive test is who switches the slot: a label is a\nsentinel carrier (`''` enables the slot) only where the label value itself toggles it. A label\nrendered through a slot the component keeps open on its own — the tree item puts its label into\nthe always-open expert slot of its embedded link — carries segments but no sentinel, so it binds\n`labelLangSegmentsProp`.\n\nThis rule binds new and changed props immediately. Existing props adopt it family by family — prop\ndefinitions first, then component signatures. Where no named schema type exists yet, it is added: an\nadditive, non-breaking change, because naming a type never changes its structure.\n\n#### Label Handling Forms\n\nSix forms govern how a label value flows through the layers. They exist because the validation\nboundary and the render boundary are different places: the web component validates untyped input\n(attributes arrive as strings, adapters pass any runtime value), while a functional component\nreceives already-normalized props and never validates.\n\n1. **A functional component trusts its props.** Its prop type comes from the props config slot\n (`required` → mandatory, `optional` → partial). A guard inside a functional component is never a\n distrust of validation — it handles the documented \"not set\" state of an optional prop (the alert\n without a label renders no heading).\n2. **The \"not set\" guard is `label?.length > 0`** for optional `string | LabelSegment[] | undefined`\n labels, in JSX conditions and ternaries alike. The expression must be strictly boolean: a bare\n `label?.length &&` renders the digit `0` into the DOM when the label is the empty string.\n3. **`trimLabel(label)` is the only way to obtain a plain string** (accessible names, aria-label,\n aria-description). `trimLabel` is undefined-safe by signature (`undefined` → `''`) and the only\n place joining segment arrays — call it without `?? ''` or `|| ''`, and never apply string\n operations to a segment array directly.\n4. **`''` is the expert-slot sentinel, everywhere.** Only components with `labelWithExpertSlotProp`\n accept it; their span switches to the expert slot. Everywhere else it is an invalid value. The\n one mapping to \"not set\" lives where an empty label is legitimate input (the tooltip behavior:\n `apply(value || undefined, …)`, mapping `''` to the unset state instead of an invalid-value\n warning).\n5. **Rendered labels go through `renderLabelWithLang`** so each segment keeps its `lang` attribute\n for screen readers. A pure `aria-label` uses `trimLabel` — language segments would have no\n effect there, which is why landmark components bind `labelProp`.\n6. **Which prop definition a component binds follows its markup** (see the variant rule above);\n the forms here stay identical for all three label definitions.\n\n#### `PropDefinition<TInternal>`\n\n`PropDefinition<TInternal>` defines `normalize` (unknown → TInternal), `validate` (TInternal → boolean), `getDefaultValue()` (→ TInternal) and `apply(value, callback)`. The normalize function accepts `unknown` because HTML attributes can arrive as any type.\n\nEach `PropDefinition` provides an `apply(value, callback)` method that combines normalization, validation and fallback handling into a single call. If the value is `undefined` or `null`, the built-in default is used. Otherwise, the value is normalized and validated before being passed to the callback — ensuring callbacks only receive type-safe internal values:\n\n```typescript\nmaxProp.apply(value, (normalized) => {\n\t// normalized is number, type-safe and validated (> 0)\n\tthis.setRenderProp('max', normalized);\n});\n```\n\n##### Undefined handling, requiredness and the default contract\n\nThree rules separate the layers, so a fachliche validator never has to deal with \"not set\":\n\n1. **Requiredness is a property of the component, decided by the props config slot.** The `required`/`optional` arrays feed `ApiFromConfig` (`Props.Required`/`Props.Optional`) _and_ drive the runtime warning: `BaseWebComponent.isRequired(key)` answers from the `required` array, and the applying watcher passes it to `apply` as its third argument (`labelProp.apply(value, cb, this.isRequired('label'))`). A prop definition itself carries no requiredness — one definition serves a required prop in one component (the link's `href`) and an optional one in another (the card's) without duplication. Appliers outside a component config (items, behaviors, `resolve-props`) apply without the argument: an unset value there is a legitimate \"not set\", not a missing required value.\n2. **`apply()` intercepts `undefined` and `null` before any fachliche validation**: after the warning when `required` was passed, the built-in default is substituted and handed to the callback. `normalize` and `validate` never see a raw `undefined` from the `apply` path.\n3. **A definition with a default must accept it as a value; a definition without a default has no fallback at all.** `createPropDefinition` takes `undefined` as a deliberate \"no default\": an unset value then flows through as \"not set\" — nothing is validated, the validator only ever sees real values (e.g. `isValidLabel` checks length only). A definition that does carry a default has its fallback validated and throws on an invalid one. Either way the fachliche validation of real values stays untouched by the \"not set\" state. The factory types this guarantee: a definition created with a default exposes a non-optional `getDefaultValue(): TInternal` (`PropDefinitionWithDefault`), so callers read the fallback without assertions.\n\n#### `DependentPropDefinition<TInternal, TDeps>`\n\nSome props require context from other props to normalize or validate correctly. `createDependentPropDefinition` extends the pattern with a `TDeps` parameter passed through to both `normalize` and `validate`. Its `apply` method takes the deps object as a third argument:\n\n```typescript\nclampedNumberValueProp.apply(\n\tvalue,\n\t(normalized) => {\n\t\tthis.setRenderProp('value', normalized);\n\t},\n\t{ min: 0, max: this.getRenderProp('max') },\n);\n```\n\n#### Type Extraction\n\n`InternalOf<P>` and `ExternalOf<P>` utility types extract the correct type for each architectural layer automatically:\n\n| Layer | Type Extractor | Example (`ColorProp`) |\n| -------------------- | -------------- | --------------------- |\n| WC `@Prop` | `ExternalOf` | `ColorPair \\| string` |\n| `@Watch` handler | `ExternalOf` | `ColorPair \\| string` |\n| WC `setRenderProp` | `InternalOf` | `ColorPair` |\n| WC `getRenderProp` | `InternalOf` | `ColorPair` |\n| Functional Component | `InternalOf` | `ColorPair` |\n\n### API Definition with `PropsConfigShape` and `ApiFromConfig`\n\nComponent APIs are defined using a runtime props config object (`PropsConfigShape`) that groups prop definitions into `required` and `optional` arrays. The `ApiFromConfig<Config, Extra>` utility type derives the full `ComponentApi` type from this config, making the props config the single source of truth for both runtime behaviour (normalization, validation, defaults) and compile-time types:\n\n```ts\nexport const skeletonPropsConfig = {\n\trequired: [nameProp],\n} as const satisfies PropsConfigShape;\n\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tMethods: { focus: () => void; toggle: () => void };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n`ApiFromConfig` automatically merges the phantom prop types from the config arrays into the `Props.Required` and `Props.Optional` fields. The WC declares the same config object as its `propsConfig` field, from which the base derives the initial render-prop defaults.\n\nThe contracts between layers are formalized through TypeScript interfaces in [`generic-types.ts`](../../internal/functional-components/generic-types.ts). These generics (`WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps`) guarantee that components share a consistent shape for props, callbacks, emitters and refs.\n\n### Methods and Automatic Promise Wrapping\n\nStencil requires that all public `@Method()` decorated methods return a `Promise`. To keep API definitions concise, `ComponentApi` allows method signatures to be defined with plain return types. The `PromiseMethod<Methods>` utility type automatically wraps each method's return type in `Promise<T>` via `WebComponentInterface`:\n\n```ts\n// API definition — simple, no Promise required\nMethods: {\n focus: () => void;\n getValue: () => number;\n};\n```\n\n```ts\n// Resolved in WebComponentInterface — automatically Promise-wrapped\nfocus: () => Promise<void>;\ngetValue: () => Promise<number>;\n```\n\n`BehaviorInterface` intentionally does **not** apply `PromiseMethod` wrapping — Behaviors stay synchronous and testable, and the `async`/`Promise.resolve()` wrapping happens at the WC layer.\n\n### Event Handler Policy\n\nWC and Behavior methods follow a clear convention based on their usage pattern:\n\n- **Callbacks, event handlers, and ref setters** are declared as **arrow class properties** (`handleClick = () => { … }`). This auto-binds them to the instance, so they can be safely passed as references without `.bind(this)` or wrapper arrows.\n- **Lifecycle methods, watchers, and public API methods** (`componentWillLoad`, `watchName`, `focus`, `toggle`) remain **prototype methods** shared across all instances for memory efficiency.\n\nBecause callbacks are already arrow properties, both render patterns are valid:\n\n```tsx\n// Pattern A: Pass arrow property directly (concise)\n<ClickButtonFC handleClick={this.handleClick} refButton={this.setButtonRef} />\n\n// Pattern B: Wrap in arrow for explicit forwarding (allows intermediate logic)\n<SkeletonFC handleClick={() => this.handleClick()} refButton={(el) => this.setButtonRef(el)} />\n```\n\n#### ⚠️ Never use `.bind(this)` with `addEventListener`/`removeEventListener`\n\nArrow function properties automatically bind `this` at definition time. **Never** create new bound instances with `.bind(this)` in DOM event registration, as this causes listener accumulation and memory leaks — `addEventListener` and `removeEventListener` must receive the **exact same function reference** to match. Use an arrow property, or a ref callback that removes the old listener before adding the new one (see `src/components/popover-button/base.tsx`, `handleToggle` + `componentDidRender`/`disconnectedCallback`).\n\n### Implementation Flow\n\n1. **Initialisation** – the base seeds the render-prop store with the defaults of `propsConfig` on the first access — earliest possible point is a `@Watch` fired by a prop assignment before `componentWillLoad`. `componentWillLoad` applies the current prop snapshot, ensuring render props reflect external values before the first render. Composed Behaviors are initialized here too.\n2. **Prop updates** – `@Watch` handlers receive raw values, normalize/validate them via schema helpers, and store the result with `setRenderProp`.\n3. **Rendering** – the WC reads render props via `getRenderProp` and feeds them into the FC.\n4. **User interaction** – the FC emits DOM events / calls callbacks. The WC wires these back into its own handlers (or Behavior methods) so state transitions remain encapsulated.\n\n### Props Pattern\n\nA critical design principle is that **functional components always render using Props**, which are either:\n\n1. **Normalized and validated external props** — incoming props processed through schema helpers\n2. **Internal component state** — derived or computed values managed by the WC via `@State`\n\nThis ensures the renderer never works with raw, unvalidated data. Props must always be initialized before being passed to the FC (the seeding from `propsConfig` on the first access guarantees this).\n\n### Watcher Example\n\nIncoming props are normalized in dedicated watchers directly inside the WC:\n\n```ts\n// Prop definition (internal/props/name.ts); NamePropType is imported from schema/props/name.ts\ntype NameProp = SimpleProp<'name', NamePropType>;\nconst nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n```tsx\n// Web Component (src/components/<component>/component.tsx)\n@Prop() public _name!: NamePropType;\n\n@Watch('_name')\npublic watchName(value?: NamePropType): void {\n\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n}\n```\n\nThe `apply()` method uses the default value built into `nameProp` when the incoming value is `undefined` or `null`.\n\n### WC State Management\n\nThe WC manages two kinds of state directly:\n\n**Normalized Props** (via `setRenderProp()`):\n\n- Stored in the render-prop map after validation\n- Updated by watchers (e.g. `watchName`)\n- Never trigger Stencil re-renders on their own\n- Retrieved via `getRenderProp(key)` for rendering\n\n**Derived/Managed State** (via `@State` + `setState()`/`getState()`):\n\n- Stored in `@State` fields on the WC\n- Used for computed or UI state (e.g. `count`, `show`, `ariaCurrent`)\n- Each `setState()` assignment triggers a Stencil re-render\n- Read back with `getState(key)`\n\n**Rule**: a prop watcher should call `setRenderProp()` to store the normalized value. Add a `setState()` call only for `@State` fields that require reactive updates. This minimizes re-renders while keeping code clear:\n\n```tsx\n@Watch('_name')\npublic watchName(value?: string): void {\n\tnameProp.apply(value, (v) => {\n\t\tthis.setRenderProp('name', v); // Store normalized prop (no re-render)\n\t\t// this.setState('name', v); // Add only if 'name' is also an @State field\n\t});\n}\n```\n\n### WC Initialization\n\nThe WC declares its props config as the `propsConfig` field; the base seeds the render-prop store from it on the first access. `componentWillLoad` applies the current prop values and initializes composed Behaviors:\n\n```tsx\n// Web Component\nprotected readonly propsConfig: PropsConfigShape = skeletonPropsConfig;\n\npublic componentWillLoad(): void {\n\tnameProp.apply(this._name, (v) => this.setRenderProp('name', v));\n\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n}\n```\n\n## 5. Building Block View\n\n```mermaid\nclassDiagram\n direction LR\n class WebComponent {\n +componentWillLoad()\n +watchName()\n +render()\n #setState(key, value)\n #getState(key)\n #setRenderProp(key, value)\n +getRenderProp(key)\n }\n class TooltipBehavior {\n +componentWillLoad(props)\n +watchLabel(value)\n +watchAlign(value)\n +getRenderProp(key)\n }\n class LinkFC {\n +render(props)\n }\n class SchemaHelpers {\n +nameProp.apply()\n +labelProp.apply()\n }\n WebComponent ..> SchemaHelpers : normalizes via\n WebComponent --> LinkFC : renders with render props\n WebComponent o--> TooltipBehavior : composes, optional\n```\n\n**Web Component** — implements `WebComponentInterface`, owns the lifecycle, normalizes props, manages reactive state, composes optional Behaviors, and renders the FC.\n\n**TooltipBehavior** — implements `BehaviorInterface`, encapsulates a single reusable concern (tooltip show/hide, listener syncing, positioning). Composed by any WC that needs it.\n\n**LinkFC** — implements `FunctionalComponentProps`, receives the render props and produces JSX without touching state.\n\n**Schema helpers** — provide deterministic data normalization and validation functions reused across all WCs.\n\n## 6. Runtime View\n\nThe following sequence demonstrates how an external update is normalized and validated before it propagates to the renderer. The WC handles normalization directly — there is no intermediate layer.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant WC as WebComponent\n participant FC as FunctionalComponent\n participant S as Schema\n U->>WC: set attribute _name=\"Alice\"\n WC->>S: nameProp.apply(\"Alice\", callback)\n S->>S: normalize(\"Alice\") → \"Alice\"\n S->>S: validate(\"Alice\") → true\n S-->>WC: callback(\"Alice\")\n WC->>WC: setRenderProp('name', \"Alice\")\n WC->>FC: render(renderProps)\n FC-->>WC: markup\n WC-->>U: updated DOM\n Note over S,WC: apply() combines normalize + validate + callback\n Note over WC,FC: renderProps contain normalized/validated data or @State\n```\n\nThis runtime view highlights how the WC normalizes and validates external values before any rendering occurs. Only after the WC updates its render props does it invoke the functional component, patch the returned markup and expose the updated DOM to the user.\n\n## 7. Deployment View\n\nThe skeleton ships as part of the `@public-ui/components` package. During build the Stencil compiler produces framework-agnostic bundles ready for distribution via npm or CDN.\n\n## 8. Cross-cutting Concepts\n\n| Concept | Description |\n| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Composition over inheritance** | WCs compose Behaviors (e.g. `TooltipBehavior`) for reusable logic rather than relying on inheritance. |\n| **Orchestrator WC** | The WC is the single orchestrator: it normalizes props, manages state, and renders. No controller/aspect class sits between the element and the FC. |\n| **BemRootNodeFC pattern** | FCs render a single root `<div>` via `BemRootNodeFC`, with a type-checked `block` and `modifiers`. Produces `<div class=\"kol-block kol-block--…\">`; inner elements use BEM element classes. |\n| **Embedded components through items** | A component that embeds another component in its own shadow DOM renders that component's FC directly; an item (`createButtonItem`, …) owns the orchestration of each embedded instance. |\n| **Declarative rendering** | Functional components are pure and stateless. |\n| **Event-driven communication** | User interaction is emitted as DOM events/callbacks rather than calling functions across layers. |\n| **Props Pattern** | Functional components exclusively receive Props that contain either normalized/validated external data or internal component state. Props must always be initialized. |\n| **Shadow DOM First** | WCs use `shadow: true`; `shadow: false` is reserved for the transitional pattern. Components that never need an element wrapper are plain FCs. |\n| **ARIA ID Uniqueness via readable nonce IDs** | Any DOM `id` referenced by ARIA attributes (e.g. `aria-controls`, `aria-labelledby`) must be unique per component instance and follow the pattern `readable-identifier-<nonce>`. Use `private readonly someId = createUniqueId('readable-identifier')` from `utils/dev.utils`. This prevents ID collisions when components are composed inside a shared DOM scope (e.g. multiple WC instances within one shadow root, or direct light-DOM usage). Shadow DOM alone is not sufficient when a shadow component renders multiple instances of an internal WC in the same shadow root. |\n| **State ownership** | The WC owns reactive state (`@State`) and render props; the FC consumes them. |\n| **Type safety** | `WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps` encode compile-time contracts between layers. |\n| **Explicit schema types** | Every prop has exactly one named schema type in `src/schema/props`; prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining native types (the stenciljs/core#4663 alias caveat is confined to the jest toolchain). |\n| **Styling boundary** | A component's `style.scss` is base styling: layout and structure only, no colors (except the black/white contrast fallback), no spacing and no dark/light color scheme (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Colors, spacing and color schemes are implemented in the theme packages. See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](../../../../../docs/BASE_STYLING_VS_THEMING_CONCEPT.md). |\n| **Watcher placement** | Attach `@Watch` only to underscored public props (e.g. `_name`); internal state fields use `@State`. |\n\n## 9. Design Decisions\n\n1. **Eliminate the Aspect layer**\n - _Previous architecture_: a separate `BaseAspect` class sat between the WC and the FC (`WC → Aspect → FC`).\n - _Reason_: the relationship was strictly 1 WC : 1 Aspect, so the Aspect was pure indirection — every watcher and render-prop access was a pass-through. The WC can manage render props directly (the base seeds them from the declared `propsConfig` field on first access; reads and writes go through `getRenderProp`/`setRenderProp` on `BaseWebComponent`). Removing the layer halves the number of classes per component, removes a constructor/`StateAccess` handoff, and keeps the data flow in one place. Only genuinely composable, cross-component logic survives as a `Behavior`.\n2. **Behaviors for genuinely shared logic only**\n - _Alternative_: also extract per-component logic into a dedicated behavior/controller.\n - _Reason_: a Behavior earns its existence only when the same logic is reused across multiple components (e.g. `TooltipBehavior`). Single-use logic stays as private methods on the WC.\n3. **Underscored public props**\n - _Alternative_: mirror external props directly without underscores.\n - _Reason_: underscores make the separation between public API and internal state explicit.\n4. **Shadow DOM enabled for web components (shadow: true)**\n - _Alternative_: allow some components to have `shadow: false`.\n - _Reason_: Shadow DOM ensures consistent style isolation and prevents CSS conflicts from host page styles, eliminating a category of hard-to-debug styling issues.\n5. **Embedded components render their FC through items**\n - _Alternative_: render a `shadow:false` element (`kol-button-wc`, …) inside the embedding component's shadow DOM, so its stylesheet reaches the inner `.kol-…` classes.\n - _Reason_: such an element duplicates the orchestrator of the public element and puts an extra node between the embedding component and the embedded block. An item keeps one orchestration per embedded instance in the embedding WC and renders the FC root in place of the element.\n6. **Centralised validation in the WC**\n - _Alternative_: perform validation scattered inside prop watchers without schema helpers.\n - _Reason_: routing all external values through `PropDefinition.apply()` keeps validation, defaults and normalization in one reusable, testable place.\n7. **Functional component rendering**\n - _Alternative_: render JSX directly inside the web component class.\n - _Reason_: a pure renderer improves testability and eliminates side effects.\n8. **Generic interface contracts**\n - _Alternative_: rely on ad-hoc typing per component.\n - _Reason_: shared interfaces keep props, callbacks, emitters and refs uniform across components, making WCs, Behaviors and renderers interchangeable.\n9. **@State for managed UI state, render props for normalized props**\n - _Pattern_: public props (e.g. `_name`) are normalized and stored as render props. UI state that is managed but not exposed as props (like `count`, `show`, `ariaCurrent`) uses `@State` to trigger reactive re-renders.\n - _Reason_: normalized props do not need `@State` — they are held as render props and accessed via `getRenderProp(key)`. This avoids unnecessary re-rendering while keeping reactive state explicit.\n10. **Host element without redundant class attribute**\n - _Alternative_: add the component name as a class attribute to `<Host>` (e.g. `<Host class=\"kol-abbr\">`).\n - _Reason_: the tag name alone (e.g. `<kol-abbr>`) plus Shadow DOM are sufficient for styling and identification. The BEM root class is emitted by `BemRootNodeFC` inside the FC, not on `<Host>`.\n11. **Omit unused API fields in ComponentApi definitions**\n - _Pattern_: all fields in `ComponentApi` are optional except `States` (`Props`, `Emitters`, `Methods`, `Callbacks`, `Refs`, `Listeners` — `States` is required and defaults to `Record<never, never>` via `ApiFromConfig`). Only define the fields the component actually uses. The generic type extraction in `generic-types.ts` safely defaults missing fields to empty records.\n - _Alternative_: define all fields explicitly, using empty records for unused ones.\n - _Reason_: a minimal API definition is easier to read and accurately conveys what the component does.\n12. **ARIA ID uniqueness via `createUniqueId()`**\n - _Pattern_: any `id` referenced by an ARIA relation attribute must be unique per instance. Declare stable base ids as `private readonly xId = createUniqueId('x')` and derive related ids with `createRelatedUniqueId(baseId, 'control')`.\n - _Alternative_: hardcode a static string.\n - _Reason_: Shadow DOM scopes IDs per shadow root, but a parent may render multiple instances of an internal WC in the same shadow root, colliding IDs. `createUniqueId()` is cheap and eliminates this category of bug, and also covers direct light-DOM usage.\n13. **No `data-testid` — use BEM class selectors in tests**\n - _Pattern_: do not add `data-testid` attributes. Tests select elements via their BEM class names (`page.locator('.kol-component__element')`).\n - _Alternative_: add `data-testid` and use `getByTestId()`.\n - _Reason_: BEM class names are already present, stable, and semantically tied to the component. Using them keeps production markup clean of test-only concerns.\n14. **Test co-location — all tests live next to the component**\n - _Pattern_: all test files sit directly alongside `component.tsx` — snapshot tests (`snapshot.spec.tsx`, Jest) and interaction tests (`interaction.e2e.ts`, Playwright). File names are uniform across components.\n - _Alternative_: group tests into a dedicated `test/` subdirectory.\n - _Reason_: co-located tests are easier to discover and keep related files visible side-by-side.\n15. **Public API parity during migration — the FC face is not the public face**\n - _Pattern_: a skeleton migration keeps the WC's public `@Prop`/`@Method` set byte-identical to the predecessor: same members, same schema-alias types, same defaults, same JSDoc (including `@deprecated`). The WC implements the schema `*Props` interface alongside `WebComponentInterface<Api>` so drift fails the build. Internal FC props without a public predecessor prop stay internal (fed from defaults, no public `@Prop` added).\n - _Alternative_: expose every FC prop 1:1 as a public `@Prop` and declare props with the internal primitive types.\n - _Reason_: the public API is a compatibility contract (adapters, IntelliSense, `custom-elements.json` are generated from `prop.docs`/`method.docs`). Growing it silently (e.g. link gained `_ariaOwns`, `_customClass`, `_tabIndex`, `click()`) or dropping its documentation is a breaking change disguised as a refactor. See [§4 Public API Contract](#public-api-contract-migration-parity).\n16. **Shared orchestrator base for tag variants of one FC**\n - _Pattern_: elements that render the same FC (`kol-button`/`kol-button-link`/`kol-split-button`, `kol-link`/`kol-link-button`) share an abstract, decorator-free base class next to the element (`button/base.tsx`, `link/base.tsx`) that extends `BaseWebComponent<Api>` and holds Behaviors, handlers, `apply<Prop>()` methods and the FC render call. The concrete element declares the Stencil members and delegates from its watchers and lifecycle methods.\n - _Alternative_: copy the orchestrator into every element (the state before this decision: ~350 identical lines in `component.tsx` and `wc.tsx`), or let the variants instantiate a `shadow:false` twin of the public element.\n - _Reason_: the base is not a layer between WC and FC (decision 1 stays intact) — it _is_ the WC's implementation, written once. Stencil only reads decorators and lifecycle hooks from the component class itself, so those stay there; plain methods and fields are inherited at runtime like the ones of `BaseWebComponent`. Anything that needs the host element (e.g. the form-association controller) is created from the concrete constructor after `super()`, because Stencil registers the host at the start of the component class's constructor.\n17. **DOM structure and BEM classes are a theming contract, not public API**\n - _Pattern_: a change of the internal DOM structure or of the BEM classes it needs ships in at least a minor release as a **theming breaking change**: release label `release:theming`, old and new classes listed in the pull request, all themes of this repository adapted in the same change. See [Theming Contract](#theming-contract-shadow-dom-structure-and-bem-classes).\n - _Alternative_: treat every class or node change as a breaking change that waits for the next major release.\n - _Reason_: themes can be adapted to such a change largely automatically through their own visual snapshots and the zero-visual-delta workflow. Holding back structural cleanups (single BEM root, registered classes) until a major release would keep known non-conformities alive for a long time without protecting anyone more than the changelog entry does.\n18. **Explicit schema types per prop**\n - _Pattern_: every prop's value type is the named schema type from `src/schema/props`; the prop bag, the prop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all reference that name, and no layer inlines a native type. See [Explicit Schema Types per Prop](#explicit-schema-types-per-prop).\n - _Alternative_: type prop definitions and component signatures with bare natives (`SimpleProp<'disabled', boolean>`) and keep the schema name only on the prop bag.\n - _Reason_: the type is defined once and every layer points at the same name, so drift between the layers fails the compiler instead of surfacing in review; apply and watcher signatures carry the domain term; and the prop definitions binding one render key are connected by their shared schema type, not only by the key string. Naming a type never changes its structure, so adopting it is invisible to consumers. The pinned Stencil's un-coerced attribute parsing for imported aliases (stenciljs/core#4663) is a known test-toolchain caveat, not a reason to inline natives.\n\n## 10. Quality Requirements\n\n- Maintainability: the WC is the single orchestrator, reducing the number of classes and the cost of change.\n- Reliability: schema helpers validate every external value before it mutates state.\n- Testability: the FC is a pure renderer and can be unit tested in isolation; Behaviors can be tested standalone. Snapshot tests (Jest) verify DOM output; interaction tests (Playwright) verify user-facing behaviour.\n- Performance: **optimized re-rendering** — public props are normalized and stored as render props (no re-render); only `@State` changes trigger re-renders. Stencil batches simultaneous prop/state changes into a single re-render.\n- Accessibility: follow repository-wide a11y presets and prefer `KolTooltip` over `title` attributes.\n- Security: avoid direct DOM injection; rely on typed props and validation to prevent XSS.\n\n## 11. Risks and Technical Debt\n\n- The transitional `shadow:false` WCs are temporary scaffolding; they should be removed as consumers migrate to render FCs directly.\n- WCs with many props can accumulate verbose watcher boilerplate; the `PropDefinition.apply()` pattern keeps each watcher to one line, but a component with dozens of props still produces dozens of watchers.\n- Behaviors that hold listener references must clean up in `disconnectedCallback` to avoid leaks (see the Event Handler Policy warning).\n\n## 12. Glossary\n\n| Term | Definition |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **BEM** | Block Element Modifier naming convention for CSS class names. |\n| **BemRootNodeFC** | Single-root BEM wrapper FC. Renders one `<div class=\"kol-block kol-block--…\">` from a type-checked `block` and `modifiers`. |\n| **Behavior** | Optional, composable unit of reusable logic living inside a WC; extends `BaseBehavior`. Example: `TooltipBehavior`. |\n| **Orchestrator (WC)** | The web component, which directly owns lifecycle, prop normalization, state management, Behavior composition and rendering. |\n| **Functional Component** | Pure renderer without side effects that exclusively works with Props. |\n| **Props** | Normalized and validated props or internal state passed to functional components. Must always be initialized. |\n| **Render props** | Validated, normalized prop values stored on the WC via `setRenderProp` and read via `getRenderProp` for rendering. |\n| **Schema Helper** | Utility providing `normalize` (unknown → TInternal), `validate` (TInternal → boolean) and `apply` (normalize + validate + callback) for props. |\n| **Schema Type** | Named value type of one prop in `src/schema/props` (e.g. `DisabledPropType`); the single spelling every layer references. |\n| **StateAccess** | `{ setState, getState }` bundle a WC passes to a Behavior; `BaseWebComponent.stateLess` is the no-op sentinel for stateless Behaviors. |\n| **Stencil** | Compiler for building framework-agnostic web components. |\n| **Transitional WC** | A `shadow:false` WC that renders an FC into the light DOM so legacy consumers can reach inner BEM classes; deleted once consumers migrate. |\n| **Watch Decorator** | Stencil decorator (`@Watch`) that observes prop changes. |\n",
3664
3640
  "kind": "spec"
3665
3641
  },
3666
3642
  {
@@ -3944,7 +3920,7 @@
3944
3920
  "group": "spec",
3945
3921
  "name": "pagination",
3946
3922
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/pagination.md",
3947
- "code": "# kol-pagination\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_boundaryCount` | `_boundary-count` | Defines the amount of pages to show next to the outer arrow buttons. | `number \\| undefined` | `1` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_hasButtons` | `_has-buttons` | Defines which navigation buttons to render (first, last, next, previous buttons). | `boolean \\| string \\| undefined \\| { first: boolean; last: boolean; next: boolean; previous: boolean; }` | `true` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n| `_max` _(required)_ | `_max` | Defines the maximum value of the element. | `number` | `undefined` |\n| `_on` _(required)_ | -- | Gibt an, auf welche Callback-Events reagiert werden. | `{ onChangePage?: EventValueOrEventCallback<Event, number> \\| undefined; onChangePageSize?: EventValueOrEventCallback<Event, number> \\| undefined; onClick?: EventValueOrEventCallback<Event, number> \\| undefined; }` | `undefined` |\n| `_page` _(required)_ | `_page` | Defines the current page. | `number` | `undefined` |\n| `_pageSize` | `_page-size` | Defines the amount of entries to show per page. | `number` | `1` |\n| `_pageSizeOptions` | `_page-size-options` | Defines the options for the page-size-select. | `number[] \\| string` | `[]` |\n| `_siblingCount` | `_sibling-count` | Defines the amount of pages to show next to the current page. | `number \\| undefined` | `1` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n\n\n----------------------------------------------\n\n\n",
3923
+ "code": "# kol-pagination\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_boundaryCount` | `_boundary-count` | Defines the amount of pages to show next to the outer arrow buttons. | `number \\| undefined` | `1` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_hasButtons` | `_has-buttons` | Defines which navigation buttons to render (first, last, next, previous buttons). | `boolean \\| string \\| undefined \\| { first: boolean; last: boolean; next: boolean; previous: boolean; }` | `true` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_max` _(required)_ | `_max` | Defines the maximum value of the element. | `number` | `undefined` |\n| `_on` _(required)_ | -- | Gibt an, auf welche Callback-Events reagiert werden. | `{ onChangePage?: EventValueOrEventCallback<Event, number> \\| undefined; onChangePageSize?: EventValueOrEventCallback<Event, number> \\| undefined; onClick?: EventValueOrEventCallback<Event, number> \\| undefined; }` | `undefined` |\n| `_page` _(required)_ | `_page` | Defines the current page. | `number` | `undefined` |\n| `_pageSize` | `_page-size` | Defines the amount of entries to show per page. | `number` | `1` |\n| `_pageSizeOptions` | `_page-size-options` | Defines the options for the page-size-select. | `number[] \\| string` | `[]` |\n| `_siblingCount` | `_sibling-count` | Defines the amount of pages to show next to the current page. | `number \\| undefined` | `1` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n\n\n----------------------------------------------\n\n\n",
3948
3924
  "kind": "spec"
3949
3925
  },
3950
3926
  {
@@ -3992,15 +3968,6 @@
3992
3968
  "code": "# kol-single-select\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **SingleSelect** component creates a dropdown list from which exactly one predefined option can be selected.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasClearButton` | `_has-clear-button` | Shows the clear button if enabled. | `boolean \\| undefined` | `true` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames (e.g. `icons=\"fa-solid fa-user\"`). | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` _(required)_ | `_options` | Options the user can choose from. | `Option<StencilUnknown>[] \\| string` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `null` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3993
3969
  "kind": "spec"
3994
3970
  },
3995
- {
3996
- "id": "spec/skeleton",
3997
- "group": "spec",
3998
- "name": "skeleton",
3999
- "description": "Focuses the interactive element of the component.",
4000
- "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/skeleton.md",
4001
- "code": "# kol-skeleton\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------- | ---------------------------------------- | -------- | ----------- |\n| `_name` _(required)_ | `_name` | Sets the name of the skeleton component. | `string` | `undefined` |\n\n\n## Events\n\n| Event | Description | Type |\n| ---------- | --------------------------------------------------------------- | --------------------- |\n| `loaded` | Emitted when the skeleton has finished loading. | `CustomEvent<number>` |\n| `rendered` | Emitted when the skeleton has been rendered for the first time. | `CustomEvent<void>` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nFocuses the interactive element of the component.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `toggle() => Promise<void>`\n\nToggles the visibility of the skeleton component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
4002
- "kind": "spec"
4003
- },
4004
3971
  {
4005
3972
  "id": "spec/skip-nav",
4006
3973
  "group": "spec",
@@ -4033,7 +4000,7 @@
4033
4000
  "name": "table-stateful",
4034
4001
  "description": "The Table component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.",
4035
4002
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateful.md",
4036
- "code": "# kol-table-stateful\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Table** component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_allowMultiSort` | `_allow-multi-sort` | Defines whether to allow multi sort. | `boolean \\| undefined` | `undefined` |\n| `_ariaLabelledby` | `_aria-labelledby` | References an external element by ID that serves as the accessible label for this table. Uses ElementInternals.ariaLabelledByElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS) — use `_label` instead. | `string \\| undefined` | `undefined` |\n| `_data` _(required)_ | `_data` | Defines the primary table data. | `KoliBriTableDataType[] \\| string` | `undefined` |\n| `_dataFoot` | `_data-foot` | Defines the data for the table footer. | `KoliBriTableDataType[] \\| string \\| undefined` | `undefined` |\n| `_fixedCols` | -- | Defines the fixed number of columns from start and end of the table | `[number, number] \\| undefined` | `undefined` |\n| `_hasSettingsMenu` | `_has-settings-menu` | Enables the settings menu if true (default: false). | `boolean \\| undefined` | `undefined` |\n| `_headers` _(required)_ | `_headers` | Defines the horizontal and vertical table headers. | `string \\| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; }` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string` | `undefined` |\n| `_loading` | `_loading` | Wether the table shows a loading spinner (default: false). | `boolean \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for table events. | `undefined \\| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \\| undefined; }` | `undefined` |\n| `_pagination` | `_pagination` | Defines whether to show the data distributed over multiple pages. | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _label?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition` | `_pagination-position` | Controls the position of the pagination. | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n### `resetSort() => Promise<void>`\n\nResets the sort state to the default values defined in the `_headers` prop.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
4003
+ "code": "# kol-table-stateful\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Table** component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_allowMultiSort` | `_allow-multi-sort` | Defines whether to allow multi sort. | `boolean \\| undefined` | `undefined` |\n| `_ariaLabelledby` | `_aria-labelledby` | References an external element by ID that serves as the accessible label for this table. Uses ElementInternals.ariaLabelledByElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS) — use `_label` instead. | `string \\| undefined` | `undefined` |\n| `_data` _(required)_ | `_data` | Defines the primary table data. | `KoliBriTableDataType[] \\| string` | `undefined` |\n| `_dataFoot` | `_data-foot` | Defines the data for the table footer. | `KoliBriTableDataType[] \\| string \\| undefined` | `undefined` |\n| `_fixedCols` | -- | Defines the fixed number of columns from start and end of the table | `[number, number] \\| undefined` | `undefined` |\n| `_hasSettingsMenu` | `_has-settings-menu` | Enables the settings menu if true (default: false). | `boolean \\| undefined` | `undefined` |\n| `_headers` _(required)_ | `_headers` | Defines the horizontal and vertical table headers. | `string \\| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; }` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string` | `undefined` |\n| `_loading` | `_loading` | Wether the table shows a loading spinner (default: false). | `boolean \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for table events. | `undefined \\| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \\| undefined; }` | `undefined` |\n| `_pagination` | `_pagination` | Defines whether to show the data distributed over multiple pages. | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _label?: string \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition` | `_pagination-position` | Controls the position of the pagination. | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n### `resetSort() => Promise<void>`\n\nResets the sort state to the default values defined in the `_headers` prop.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
4037
4004
  "kind": "spec"
4038
4005
  },
4039
4006
  {