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

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-12T14:19:29.502Z",
3
+ "generatedAt": "2026-11-17T10:58:19.735Z",
4
4
  "buildMode": "ci",
5
5
  "counts": {
6
- "total": 345,
6
+ "total": 346,
7
7
  "totalDocs": 66,
8
8
  "totalSpecs": 52,
9
- "totalSamples": 208,
9
+ "totalSamples": 209,
10
10
  "totalScenarios": 19
11
11
  },
12
12
  "repo": {
13
- "commit": "9a4c82a7074a914ddbcf87f5d0a647fcacee76b5",
13
+ "commit": "d064cf3704b7745c049849897f1dd7eec9b95ead",
14
14
  "branch": "release/4",
15
15
  "repoUrl": "https://github.com/public-ui/kolibri"
16
16
  }
@@ -265,7 +265,7 @@
265
265
  "name": "ARIA_LABELLEDBY_EXTERNAL_CAPTION_CONCEPT",
266
266
  "description": "aria-labelledby mit einer String-ID ist tree-scoped: Eine <table> im Shadow DOM kann ein <h2> im Host-Dokument per IDREF nicht erreichen.",
267
267
  "path": "docs/ARIA_LABELLEDBY_EXTERNAL_CAPTION_CONCEPT.md",
268
- "code": "# Externe Tabellenbeschriftung via `_ariaLabelledby`\n\n## Problem\n\n`aria-labelledby` mit einer String-ID ist **tree-scoped**: Eine `<table>` im Shadow DOM kann ein `<h2>` im Host-Dokument per IDREF nicht erreichen.\n\n## Lösung\n\n`ariaLabelledByElements` ist Teil von `ARIAMixin` und steht auf **jedem** `Element` — nicht nur auf `ElementInternals`. Element-Referenzen (JS-Objekte) sind nicht tree-scoped und überqueren Shadow-Grenzen problemlos.\n\n## Ablauf\n\n```\n_ariaLabelledby=\"heading-id\"\n │\n ▼\nresolveTargets(host, value)\n getRootNode() → findet Elemente im korrekten Tree-Scope des Wrappers\n CSS.escape() → IDs mit Sonderzeichen werden robust behandelt\n │\n ▼\ntable.ariaLabelledByElements = [<h2>] ← ARIAMixin direkt auf <table>\ninternals.ariaLabelledByElements = [<h2>] ← zusätzlich auf dem Wrapper selbst\n```\n\nDie aufgelösten Elemente werden als `externalLabelElements`-Prop an die interne WC-Implementierung weitergereicht, die sie per Ref-Callback auf das native `<table>`-Element setzt.\n\nIst das externe Element beim ersten Render noch nicht im DOM (z. B. späte Headline), wird einmalig mit 50 ms Verzögerung nachgeladen.\n\n## Mehrere IDs\n\n`_ariaLabelledby` akzeptiert mehrere IDs (whitespace-getrennt), genau wie das native Attribut:\n\n```jsx\n<KolTableStateless _ariaLabelledby=\"heading-id subheading-id\" … />\n```\n\n`resolveTargets` teilt den String auf, löst jede ID im Tree-Scope des Wrappers auf und gibt ein `HTMLElement[]` zurück. Alle gefundenen Elemente werden gemeinsam in `ariaLabelledByElements` gesetzt — Assistive Technology verkettet deren Texte in Array-Reihenfolge zum zugänglichen Namen.\n\n## Caption-Verhalten\n\nDie `<caption>` wird immer gerendert — sie ist das Fokus-Element der Tabelle (`tabindex`).\n\n| Zustand | `<caption>` | `aria-labelledby` auf `<table>` | `ariaLabelledByElements` |\n| -------------------------- | -------------------- | ------------------------------- | ------------------------ |\n| Kein `_ariaLabelledby` | sichtbar | `\"caption\"` | — |\n| Element gefunden | `aria-hidden=\"true\"` | — | `[externes Element]` |\n| Element **nicht** gefunden | sichtbar | `\"caption\"` | — |\n\n## `attachInternals` — noch relevant?\n\n`attachInternals()` wird weiterhin auf den Shadow-Wrapper-Komponenten (`kol-table-stateless`, `kol-table-stateful`) aufgerufen. Es ist dort nicht Teil des Labeling-Mechanismus auf `<table>`, sondern dient:\n\n- **Zugänglicher Name des Wrappers selbst**: `internals.ariaLabelledByElements` gibt dem Custom-Element-Host (`<kol-table-stateless>`) einen eigenen zugänglichen Namen — nützlich für AT, die den Host inspizieren, und für Accessibility-Tree-Debugging.\n- **Vorbereitung für weitere ARIA-Properties**: `ElementInternals` ist der richtige Ort, um role, ariaRequired, ariaInvalid etc. auf einem Shadow-Host zu setzen, sobald KoliBri weitere solcher Props bekommt (→ nächster Abschnitt).\n\nBeide Tabellen rendern das `<table>` direkt in ihrem eigenen Shadow-Root; `attachInternals` gehört deshalb nur an ihren Host, die ARIAMixin-Zuweisung liegt direkt auf `<table>`.\n\n### Wichtige Warnung zu Host-Rollen\n\nDas Setzen einer Rolle auf dem Custom-Element-Host (z. B. `internals.role = 'table'`) kann Screenreader blockieren.\nIn einigen Screenreader-/Browser-Kombinationen wird der innere Inhalt der Web Component dann nicht mehr korrekt aufgelöst und vorgelesen.\n\nDringende Empfehlung:\n\n- Keine Rollen am Host setzen.\n- Semantik stattdessen auf dem nativen inneren Element setzen (z. B. auf dem tatsächlichen `<table>`).\n\n## Generalisierung auf weitere ARIA-Properties\n\nDasselbe Muster funktioniert für alle ARIA-Relationship-Properties, die in `ARIAMixin` als Element-Referenz-Variante verfügbar sind:\n\n| ARIA-Attribut | ARIAMixin-Property | Typischer Anwendungsfall |\n| ----------------------- | ----------------------------- | -------------------------------------------------------- |\n| `aria-labelledby` | `ariaLabelledByElements` | Externe Überschrift als Tabellen-Label |\n| `aria-describedby` | `ariaDescribedByElements` | Hilfetexte oder Fehlermeldungen außerhalb des Shadow DOM |\n| `aria-controls` | `ariaControlsElements` | Tabpanel, Disclosure oder Popup in anderem Tree |\n| `aria-owns` | `ariaOwnsElements` | Logische Elternschaft über Shadow-Grenzen |\n| `aria-errormessage` | `ariaErrorMessageElements` | Fehlermeldung außerhalb des Formularfeldes |\n| `aria-activedescendant` | `ariaActiveDescendantElement` | Fokus-Tracking bei Listboxen, Comboboxen |\n\nFür jede dieser Properties gilt das gleiche Rezept:\n\n1. Prop akzeptiert einen ID-String (space-separated wo sinnvoll).\n2. `resolveTargets(host, value)` löst IDs im Tree-Scope des Wrappers auf.\n3. `element.ariaXxxElements = resolvedElements` direkt auf dem Ziel-HTML-Element setzen (ARIAMixin, keine IDREFs nötig).\n4. Auf dem Shadow-Host zusätzlich `internals.ariaXxxElements` setzen (via `attachInternals`).\n\nDie einzige Besonderheit: `ariaActiveDescendantElement` ist singular (ein Element, kein Array), alle anderen sind Arrays.\n\n## Nutzung\n\n```jsx\n<h2 id=\"orders-heading\">Bestellungen</h2>\n<KolTableStateless\n _ariaLabelledby=\"orders-heading\"\n _label=\"Fallback falls Element nicht gefunden\"\n _headerCells={headers}\n _data={data}\n/>\n```\n\n## Browser-Support\n\n| Screen Reader | Browser | Funktioniert |\n| ------------- | ------------------------- | ------------ |\n| NVDA, JAWS | Chrome, Firefox (Desktop) | ✅ |\n| VoiceOver | Safari, Chrome (macOS) | ✅ |\n| TalkBack | Chrome (Android) | ❌ |\n\nTalkBack folgt `ariaLabelledByElements` nicht — Chrome übergibt Element-Referenzen nicht ans Android Accessibility Framework. Für TalkBack-Unterstützung: `_label` verwenden.\n",
268
+ "code": "# Externe Tabellenbeschriftung via `_ariaLabelledby`\n\n## Problem\n\n`aria-labelledby` mit einer String-ID ist **tree-scoped**: Eine `<table>` im Shadow DOM kann ein `<h2>` im Host-Dokument per IDREF nicht erreichen.\n\n## Lösung\n\n`ariaLabelledByElements` ist Teil von `ARIAMixin` und steht auf **jedem** `Element` — nicht nur auf `ElementInternals`. Element-Referenzen (JS-Objekte) sind nicht tree-scoped und überqueren Shadow-Grenzen problemlos.\n\n## Ablauf\n\n```\n_ariaLabelledby=\"heading-id\"\n │\n ▼\nresolveTargets(host, value)\n getRootNode() → findet Elemente im korrekten Tree-Scope des Wrappers\n CSS.escape() → IDs mit Sonderzeichen werden robust behandelt\n │\n ▼\ntable.ariaLabelledByElements = [<h2>] ← ARIAMixin direkt auf <table>\n```\n\nDie aufgelösten Elemente werden als `externalLabelElements`-Prop an die interne WC-Implementierung weitergereicht, die sie per Ref-Callback auf das native `<table>`-Element setzt.\n\nIst das externe Element beim ersten Render noch nicht im DOM (z. B. späte Headline), lösen die Komponenten erneut auf: die Tabellen beim Mount und den ersten Rendern, die Form-Felder bei jedem Render (`componentDidRender`) — unveränderte Referenzen werden nicht erneut geschrieben.\n\n## Mehrere IDs\n\n`_ariaLabelledby` akzeptiert mehrere IDs (whitespace-getrennt), genau wie das native Attribut:\n\n```jsx\n<KolTableStateless _ariaLabelledby=\"heading-id subheading-id\" … />\n```\n\n`resolveTargets` teilt den String auf, löst jede ID im Tree-Scope des Wrappers auf und gibt ein `HTMLElement[]` zurück. Alle gefundenen Elemente werden gemeinsam in `ariaLabelledByElements` gesetzt — Assistive Technology verkettet deren Texte in Array-Reihenfolge zum zugänglichen Namen.\n\n## Caption-Verhalten\n\nDie `<caption>` wird immer gerendert — sie ist das Fokus-Element der Tabelle (`tabindex`).\n\n| Zustand | `<caption>` | `aria-labelledby` auf `<table>` | `ariaLabelledByElements` |\n| -------------------------- | -------------------- | ------------------------------- | ------------------------ |\n| Kein `_ariaLabelledby` | sichtbar | `\"caption\"` | — |\n| Element gefunden | `aria-hidden=\"true\"` | — | `[externes Element]` |\n| Element **nicht** gefunden | sichtbar | `\"caption\"` | — |\n\n## Wichtige Warnung zu Host-Rollen\n\nDas Setzen einer Rolle auf dem Custom-Element-Host (z. B. `internals.role = 'table'`) kann Screenreader blockieren.\nIn einigen Screenreader-/Browser-Kombinationen wird der innere Inhalt der Web Component dann nicht mehr korrekt aufgelöst und vorgelesen.\n\nDringende Empfehlung:\n\n- Keine Rollen am Host setzen.\n- Semantik stattdessen auf dem nativen inneren Element setzen (z. B. auf dem tatsächlichen `<table>`).\n\n## Generalisierung auf weitere ARIA-Properties\n\nDasselbe Muster funktioniert für alle ARIA-Relationship-Properties, die in `ARIAMixin` als Element-Referenz-Variante verfügbar sind:\n\n| ARIA-Attribut | ARIAMixin-Property | Typischer Anwendungsfall |\n| ----------------------- | ----------------------------- | -------------------------------------------------------- |\n| `aria-labelledby` | `ariaLabelledByElements` | Externe Überschrift als Tabellen-Label |\n| `aria-describedby` | `ariaDescribedByElements` | Hilfetexte oder Fehlermeldungen außerhalb des Shadow DOM |\n| `aria-details` | `ariaDetailsElements` | Detailbereich außerhalb des Shadow DOM (Form-Felder) |\n| `aria-controls` | `ariaControlsElements` | Tabpanel, Disclosure oder Popup in anderem Tree |\n| `aria-owns` | `ariaOwnsElements` | Logische Elternschaft über Shadow-Grenzen |\n| `aria-errormessage` | `ariaErrorMessageElements` | Fehlermeldung außerhalb des Formularfeldes |\n| `aria-activedescendant` | `ariaActiveDescendantElement` | Fokus-Tracking bei Listboxen, Comboboxen |\n\nFür jede dieser Properties gilt das gleiche Rezept:\n\n1. Prop akzeptiert einen ID-String (space-separated wo sinnvoll).\n2. `resolveTargets(host, value)` löst IDs im Tree-Scope des Wrappers auf.\n3. `element.ariaXxxElements = resolvedElements` direkt auf dem nativen inneren Element setzen (ARIAMixin, keine IDREFs nötig).\n\nDie einzige Besonderheit: `ariaActiveDescendantElement` ist singular (ein Element, kein Array), alle anderen sind Arrays.\n\n## Kein `ElementInternals`\n\n`ElementInternals`-Zuweisungen (`attachInternals()`) sind bewusst entfernt: Keine KoliBri-Komponente ist form-associated (`formAssociated`), daher wirft `attachInternals()` eine `NotSupportedError` und die Schicht war nie wirksam — sie ist immer `undefined` geblieben. Der einzige Mechanismus für External-ARIA-Referenzen ist die ARIAMixin-Zuweisung auf dem nativen inneren Element.\n\n## Nutzung\n\n```jsx\n<h2 id=\"orders-heading\">Bestellungen</h2>\n<KolTableStateless\n _ariaLabelledby=\"orders-heading\"\n _label=\"Fallback falls Element nicht gefunden\"\n _headerCells={headers}\n _data={data}\n/>\n```\n\n## Browser-Support\n\n| Screen Reader | Browser | Funktioniert |\n| ------------- | ------------------------- | ------------ |\n| NVDA, JAWS | Chrome, Firefox (Desktop) | ✅ |\n| VoiceOver | Safari, Chrome (macOS) | ❌ |\n| TalkBack | Chrome (Android) | ❌ |\n\nTalkBack folgt `ariaLabelledByElements` nicht — Chrome übergibt Element-Referenzen nicht ans Android Accessibility Framework. VoiceOver auf macOS meldet die Referenzen ebenfalls nicht (plattformseitige Lücke, Details und Nachweise in KNOWN_ISSUES.md). Für Screenreader, die die Referenzen nicht folgen: `_label` verwenden.\n",
269
269
  "kind": "doc"
270
270
  },
271
271
  {
@@ -414,7 +414,7 @@
414
414
  "name": "FORM_FIELD_SKELETON_MIGRATION_PLAN",
415
415
  "description": "Übergreifender Plan für die Skeleton-Migration der 14 Formularfelder von kol-combobox bis kol-textarea (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.",
416
416
  "path": "docs/FORM_FIELD_SKELETON_MIGRATION_PLAN.md",
417
- "code": "# Migrationsplan: Formularfelder auf Skeleton\n\nÜbergreifender Plan für die Skeleton-Migration der 14 Formularfelder von `kol-combobox` bis `kol-textarea` (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.\n\nStand: 27.09.2026, `@public-ui/components` 4.5.0-rc.0.\n\n## Ausgangslage\n\nVor der Migration lief keines der 14 Felder auf Skeleton. Der Legacy-Stack besteht aus:\n\n- Controller-Kette `AssociatedInputController → ControlledInputController → InputController → InputIconController → Feld-Controller`\n- State-Wrapper in `functional-component-wrappers/`, die die alten FCs in `functional-components/` rendern\n- Validatoren aus `schema/props/`\n\nAus dem Formularumfeld ist bisher nur `kol-form` auf Skeleton umgestellt.\n\n| Feld | LOC `shadow.tsx` | Render-Stack heute | Besonderheit |\n| -------------------- | --------------------------- | ------------------------------------------- | --------------------------------------------------------------- |\n| `kol-input-color` | 380 | FormField + InputContainer + Input („Trio\") | dünnstes Feld, kein `_required` |\n| `kol-input-email` | 489 | Trio | Controller erbt von Text → Password, Counter |\n| `kol-input-password` | 511 | Trio + IconButton (`KolButtonWcTag`) | `_visibilityToggle`, Basisklasse für Text und Email |\n| `kol-input-text` | 620 | Trio + Clear-Button | `_type`, Selection-API-Methoden |\n| `kol-textarea` | 498 | FormField + InputContainer + TextArea | `_adjustHeight`, `_resize`, `_rows`, Counter |\n| `kol-input-number` | 551 | Trio + Step-Buttons | Feature-Flag `inputNumberButtons`, genutzt von `table-settings` |\n| `kol-input-range` | 499 | 2× Input (range + number) + Suggestions | min/max/step, zwei synchrone Inputs |\n| `kol-input-date` | 513 (+ 219 Controller) | Trio | Date↔ISO, 5 `_type`s, `reset()` |\n| `kol-input-file` | 450 | Trio + Browse-Button (`KolButtonWcTag`) | kein `_value`, FileList, `_accept`, Drag & Drop, `reset()` |\n| `kol-input-checkbox` | 457 | FormField + FieldControl + Checkbox | Varianten default/switch/button, genutzt von `table-settings` |\n| `kol-input-radio` | 458 | FormField (fieldset) + FieldControl + Radio | `_options`, `_orientation`, alte Utils `element-click`/`-focus` |\n| `kol-select` | 222 + 404 (`kol-select-wc`) | FormField + InputContainer + NativeSelect | `pagination` rendert `kol-select-wc` direkt |\n| `kol-combobox` | 756 | Trio + CustomSuggestions + `@Listen` | Listbox, nahezu Zwilling von single-select |\n| `kol-single-select` | 849 | Trio + CustomSuggestions + `@Listen` | größtes Feld, offene Bugs #10501/#10617 |\n\n## Rahmenbedingungen\n\n- **Zero visual delta, BEM bleibt.** DOM und Klassen (`.kol-form-field`, `.kol-input-container`, `.kol-field-control` …) bleiben byte-identisch. Themes werden nicht angefasst, es gibt keinen CLI-/SCSS-Migrations-Task. Das Pixel-Gate verlangt 0 Diffs pro Theme.\n- **Formular-Anbindung 1:1 als Behavior.** Die heutige Semantik (versteckte native Elemente im Light DOM, `_syncValueBySelector`, `ariaDetails` über `attachInternals`) wandert aus der Controller-Kette in ein wiederverwendbares `FormAssociationBehavior`, das auch `kol-button` nutzt. Einen Umstieg auf natives `formAssociated` gibt es in dieser Migration nicht.\n- **Identische öffentliche API.** Gleiche `@Prop`/`@Method`-Member, Alias-Typen, Defaults und JSDoc. Die Oberfläche ist vor der Migration in `_skeleton/public-api/<komponente>.spec.ts` festgenagelt.\n\n## Leitplanken\n\n- **Strangler statt Big Bang.** Der neue Stack entsteht unter `internal/functional-components/form-field/` neben dem alten. Ein Legacy-Modul wird in dem PR gelöscht, der seinen letzten Import entfernt.\n- **Keine Bugfixes in Migrations-PRs.** Bekannte Fehler (z. B. #10501, #10617) bekommen eigene PRs, vor oder nach der Migration.\n- **Innere Tags bleiben.** `KolButtonWcTag` (IconButton, Clear-, Browse- und Visibility-Button) und `KolPopoverButtonWcTag` (Label-`_infoPopover`) bleiben wegen Zero-Delta stehen. Das ist eine begründete Ausnahme nach Fallstrick 8 im Skill `migrate-to-skeleton`.\n- **Grenze von DD16.** Stencil liest Decorators nur aus der konkreten Klasse. Alle `@Prop`/`@Watch`/`@Method` samt JSDoc bleiben in jeder Komponente, Basisklassen bündeln nur Logik. Höchstens zwei Ebenen unter `BaseWebComponent`.\n- **Basisklasse nach G1 eingefroren.** Änderungen an `BaseFormFieldWebComponent` kommen nur als eigenes PR, mit Pixel-Gate über alle bereits migrierten Felder.\n- **Konfliktstellen.** `internal/props/index.ts`, `schema/bem-registry.ts` und die Pin-Dateien: nur anhängen, Reihenfolge zwischen den Spuren absprechen.\n\n### Abnahme-Gates je Komponenten-PR\n\n1. Der Public-API-Pin ist unverändert und zeigt jetzt auf `component.tsx`. Die Klasse implementiert `*Props`.\n2. Die Jest-`.snap`-Dateien sind unverändert.\n3. `node scripts/snapshots-docker.mjs <theme> --check` meldet 0 Diffs für default, bwst, desy, kern und ecl (ec/eu).\n4. Die Verhaltensverträge aus G0 sind grün.\n5. Die geteilten E2E-Helfer `src/e2e/{input-msg,input-value-reflection,input-character-limit}.ts` sind grün.\n6. Keine Imports mehr aus `@deprecated/input`, `input-adapter-leanup`, `functional-component-wrappers` oder den alten `functional-components/*`.\n7. `form.e2e` ist grün: Ein Klick in der Fehlerliste fokussiert das Feld über seinen `focus()`.\n\n## Reihenfolge und Abhängigkeiten\n\n```\nG0 ─► G1.1 ─┬─► G1.2 ──┐\n └─► G1.3 ──┴─► G1.4 (Pilot input-color)\n ├─► G2 Textfelder (Spur A)\n ├─► G3 a | b | c (Spur B)\n └─► G4-Vorbereitung ─► G4 ─► G5 (Spur C)\nRückbau-Inkremente am Ende jeder Gruppe; finaler Rückbau (G6) nach G2–G5\n```\n\n## Gruppen\n\n### G0 – Absicherung\n\nKein Produktivcode, Voraussetzung für alles. Die Gates greifen nur, wenn vorher festgehalten ist, was „unverändert\" heißt: API, Verhalten und Pixel.\n\n- ✅ Public-API-Pins für alle 14 Tags und `kol-select-wc` (als interner Vertrag), zunächst gegen `shadow.tsx`. Jede Komponente hat eine eigene Datei unter `_skeleton/public-api/`, damit parallele Spuren keine Merge-Konflikte bekommen.\n- ✅ Verhaltensverträge pro Feld: Reihenfolge und Payload von `kolChange`/`kolInput`/`kolFocus`/`kolBlur`/`kolKeydown`/`kolClick` und der `_on`-Callbacks; `FormData` eines nativen `<form>` für Checkbox, `select` multiple, File und Radio mit Objektwerten; `_syncValueBySelector`; `_touched` nach Blur. Die Verträge sind Playwright-Tests (`*.e2e.ts`), weil versteckte Light-DOM-Elemente, `attachInternals`, `FormData` sowie Fokus und Tastatur nur im echten Browser verlässlich prüfbar sind. Sie nutzen die Helfer aus `src/e2e/`. Reine Umrechnungen ohne Browserverhalten (z. B. Date↔ISO in G3) werden als Jest-Tests der Hilfsfunktionen geprüft.\n - Der gemeinsame Helfer `testInputBehaviorContract` in `src/e2e/input-behavior-contract.ts` zeichnet Events und Callbacks auf; jedes Feld pinnt darin sein heutiges Verhalten. Alle 14 Felder sind gepinnt, dazu die Varianten Radio mit Objektwerten und `kol-select` mit `_multiple` (Option `variant`).\n - Befunde aus den Verträgen: Die gepinnten Abläufe beschreiben den heutigen Stand, auch wo er inkonsistent ist. Korrekturen kommen als eigene PRs nach der jeweiligen Migration.\n - Standard (G1.4, alle Felder außer den unten genannten Abweichungen): Je Aktion kommt zuerst das KoliBri-Event am Host, dann der `_on`-Callback, dann das native Event. Natives `input`/`change` endet an der Shadow-Grenze.\n - Startwert ohne Vorgabe: `kol-input-color` `#000000` (aus dem inneren Input in `componentDidLoad`), `kol-input-range` `50`, `kol-input-checkbox` `true`, `kol-input-radio` und `kol-single-select` `null`, alle anderen `undefined`.\n - G3: Payloads sind typisiert – number und range liefern Zahlen, date den ISO-String, file eine `FileList`. Für file bleibt ein Text-Input als `_syncValueBySelector`-Ziel leer.\n - G4: checkbox und radio senden kein KoliBri-`click` und keinen `onClick` (`onClick: undefined` in `shadow.tsx`). Stattdessen erreicht das native `click` den Host vor `input`/`change`.\n - G5: `kol-single-select` sendet beim Blur zuerst das native Event, dann das KoliBri-Event und den Callback. `kol-select` setzt `_touched` am eigenen Host nicht, das innere `kol-select-wc` hält den Zustand. Außerdem überträgt `kol-select` einen Einzelwert weder in `FormData` noch in das `_syncValueBySelector`-Ziel, weil das versteckte `<select multiple>` nur Array-Werte übernimmt. Mit `_multiple` stehen alle gewählten Werte in `FormData`. Issues: #11014 (`_touched`, behoben in G5.2), #11015 (Einzelwert, behoben nach G5.4).\n - Radio mit Objektwerten liefert das Objekt als Payload und überträgt es als JSON-String in `FormData` und an `_syncValueBySelector`.\n - Formular-Anbindung heute: Das versteckte Element im Light DOM entsteht nur mit `register(…, { reflectInputValues: true })`, seinen `name` setzt der Controller nur im Experimental-Mode. Nur mit beidem steht das Feld in `FormData`. Der Vertrag pinnt alle drei Fälle, der Test ruft `register` dafür aus dem Build unter Test auf.\n- ✅ Visual-Samples ergänzen für msg, hint, disabled, hideLabel, infoPopover, Counter, Icons, `inputNumberButtons` an/aus und die Checkbox-Varianten. Neue Samples erzeugen neue Baselines und gehören in ein eigenes PR vor der ersten Migration.\n - Vorhanden: msg, hint, disabled, hideLabel, infoPopover und Icons für alle 14 Felder über `partials/cases.tsx`/`variants.tsx`, Counter bei `input-text` und `textarea`, Checkbox-Varianten `basic`/`button`/`switch`.\n - `inputNumberButtons` setzt das Theme (`theme-default` `'show'`, `theme-kern` `'hide'`); die bestehenden `input-number`-Baselines decken damit beide Zustände ab.\n - Ergänzt in #11017: Counter-Routen für `kol-input-email` und `kol-input-password`, Hint-Block für `kol-input-number`.\n- ✅ Toten Code löschen: `functional-components/inputs/Combobox/Combobox.tsx`.\n\n### G1 – Fundament + Pilot `kol-input-color` (#9673, #9577)\n\nAlle 14 Felder teilen Basis-Props, die Label/Hint/Msg-Hülle, die Formular-Anbindung und die Event-Logik. Das wird einmal gebaut und am dünnsten Feld geprüft, damit die Basisklasse an einem echten Fall entsteht. G1 besteht aus sechs PRs: G1.0 #11037, G1.1 #11038, G1.2 #11044, G1.3a #11045, G1.3b #11046 und G1.4 #11049. Alle sind gemergt.\n\n```\nG1.0 Testlücken ───────────────┬──────────────────────────────────────────────┐\nG1.1 Props ─┬─► G1.2 FormAssociationBehavior (+ kol-button) ─► SSR-Fix (eigener PR)\n │ (braucht G1.0 und G1.1) │\n └─► G1.3a FormField ─► G1.3b Container/Input ──────────────────────┴─► G1.4 Basis + kol-input-color\n```\n\n0. **Testlücken** (nur Tests):\n - Formular-Anbindung von `kol-button` gepinnt. Es entsteht kein verstecktes Formularelement, weil der Adapter in `button/base.tsx` `_name` bei der Konstruktion nicht kennt (#11036); `_syncValueBySelector` wirkt im Experimental-Mode.\n - Gate 7 mit einem `kol-input-color` als Ziel der Fehlerliste.\n - Tooltip bei `_hideLabel` für `kol-input-color`. Befund: Hat das Feld den Fokus, schließt Escape den Tooltip nicht. Das Feld sendet sein eigenes `keydown`-CustomEvent am Host, das vor der nativen Taste am Dokument ankommt und den einmaligen Escape-Listener des Tooltips verbraucht (#11032, verwandt #11033).\n - Jest-Snapshots aller Felder zusätzlich mit `_hideLabel`, `_infoPopover`, sichtbarer Msg und `_variant`.\n1. **Basis-Props** in `internal/props/`: ariaDetails, autoComplete, hideMsg, hint, `horizontalIconsProp` (Icons-Objekt der Inputs, `icons.ts` bleibt unverändert), infoPopover, `inputCallbacksProp` (`_on`), msg, readOnly, required, suggestions, syncValueBySelector (nur für das Behavior), touched und der String-Wert. `tooltipAlignProp` wird wiederverwendet, der Feld-Default `'top'` im `apply` neu gesetzt. Der veröffentlichte Typ `FormFieldLabelInfoPopoverProps` zieht in einem Schritt für alle Felder nach `schema/props/`; ein teilweiser Umzug würde in `components.d.ts` einen Alias `…1` erzeugen.\n2. **`FormAssociationBehavior`**: übernimmt `input-adapter-leanup/associated.controller.ts` 1:1, einschließlich der späten Host-Zuweisung im Konstruktor. `AssociatedInputController` wird zur Fassade über das Behavior, damit die G0-Verträge es sofort für alle Felder prüfen. `button/base.tsx` wird im selben PR umgestellt; der Button-Pin bleibt unverändert.\n3. **Shell-FCs** unter `internal/functional-components/form-field/`, nur für die Hülle von `kol-input-color`: G1.3a FormField (Label, Hint, Msg, Counter, Tooltip, Zeichengrenzen-Hinweis) mit dem ARIA-Helfer aus `getRenderStates`, G1.3b InputContainer mit Adornments, IconButton, Input und Suggestions. Neue Blöcke in `schema/bem-registry.ts`. Die alten FCs werden Adapter auf die neuen, damit Hydrate-Snapshot und Pixel-Gate die Hülle sofort über alle Felder prüfen. TextArea kommt in G2, FieldControl/Checkbox/Radio in G4, NativeSelect/Option(List)/CustomSuggestions in G5. Die `fieldset`-Wurzel von radio bleibt bis G4 auf dem alten Pfad, weil `BemRootNodeFC` nur `div` rendert.\n4. **`BaseFormFieldWebComponent`** (DD16): `apply*` der Basis-Props, ein eigenes `TooltipBehavior` pro Instanz statt der modulglobalen Map in `FormField.tsx`, Formular-Anbindung, Event-Behandlung als Ersatz für `InputController` (Reihenfolge: KoliBri-Event, dann Callback) und Render-Helfer. Damit wird `kol-input-color` migriert.\n - Die Basis ist generisch über die Feld-API. Sie greift über einen dokumentierten Self-Cast (`shared`) auf die Basis-Props zu und liefert die FormField-Props mit `getFormFieldProps()`. Gerendert wird in der konkreten Klasse, wie bei `BaseButtonWebComponent`.\n - Die Props an `InputFC` bildet die konkrete Klasse in der Schlüsselreihenfolge der alten State-Wrapper. Props, die der Legacy-State nur bei gesetztem Wert enthielt, zum Beispiel `accessKey` und `aria-keyshortcuts`, übergibt sie nur, wenn ein Wert gesetzt ist. Nur so bleiben die Attributreihenfolge im Hydrate-Snapshot und das DOM unverändert.\n - `_label={false}` bleibt wie bisher der Expert-Slot (`''`). `labelWithExpertSlotProp` allein würde daraus den String `'false'` machen.\n\nEntscheidungen:\n\n- Die Basis-Config enthält nur Props, die alle 14 Felder identisch haben: ariaDetails, disabled, hideLabel, hideMsg, hint, infoPopover, label, msg, name, on, tooltipAlign, touched. `WebComponentInterface` verlangt für jede Config-Prop einen Watcher.\n- Die Basisklasse ist generisch über die Feld-API. TypeScript löst `ResolvedProps<Api>` für ein generisches `Api` nicht auf, deshalb greift sie über einen einzigen, dokumentierten Self-Cast auf die Basis-Props zu.\n- Bewusste Abweichungen der Prop-Factory, wie in allen bisherigen Skeleton-Migrationen: `undefined` führt zum Default statt den alten Wert zu behalten, `normalizeBoolean` akzeptiert `'true'`/`'false'`, ungültige Werte werden verworfen.\n- `data-testid=\"input-counter\"`/`\"input-counter-aria\"` bleiben bis G2, weil `e2e/input-character-limit.ts` sie braucht und der DOM byte-gleich bleiben muss.\n\nRisiken: Zusammenbau von `aria-describedby` (hint, msg, Counter, Hinweis zur Zeichengrenze; heutige Eigenheiten in #11035); Attribut- und Klassenreihenfolge im Hydrate-Snapshot; die beiden Fokus-Flags aus Controller und Komponente; `attachInternals(undefined)` bei SSR/Hydrate.\n\n### G2 – Textfelder: email → password → text, danach textarea (#9579, #9582, #9585, #9602)\n\nDie vier Felder hängen heute in der Kette `InputPasswordController → InputTextEmailController → InputText/InputEmail` und teilen placeholder, autoComplete, maxLength/hasCounter/maxLengthBehavior und den Counter. pattern haben nur die drei Inputs. `spellCheck` rendern input-text und textarea (#10863 wurde in #11073 behoben).\n\nG2 besteht aus sechs PRs:\n\n```\nG2.0 Testlücken (nur Tests) ────────────────────────────────────────────────────────┐\nG1.4 ─► G2.1 Props + CounterBehavior + TextAreaFC ─► G2.2 Basis + email ─► G2.3 password ─► G2.4 text ─► G2.5 textarea\n```\n\n- G2.0: Jest-Snapshots für Zähler, Zeichengrenze, Clear-Button, Visibility-Toggle, `_multiple`, `_pattern`, `_required` und `_resize`. Bisher pinnt kein Snapshot diese Fälle. Befunde, die die Migration 1:1 übernimmt: #11051 (`_adjustHeight` schrumpft nicht), #11052 (Zähler bei `_hasCounter`/`_maxLengthBehavior` zur Laufzeit), #11053 (`has-value` uneinheitlich), #11054 (devHint zu `_autoComplete`). Der Befund #10863 (`spellCheck`) wurde in #11073 behoben.\n- G2.1: Props der Textfelder in `internal/props/`; `CounterBehavior` unter `internal/functional-components/counter/` (besitzt `hasCounter`, `maxLength` und `maxLengthBehavior`, `CounterDomUpdater` ist bis G2.5 Fassade darüber); `TextAreaFC` mit dem neuen Block `kol-textarea` und das alte `inputs/TextArea` als Adapter; `getFormFieldProps()` der Basis reicht zusätzlich `required`, `readOnly`, `maxLength` und `counter` durch.\n- G2.2: `BaseTextInputWebComponent` (`internal/functional-components/text-input/`) für email, password und text, damit wird `kol-input-email` migriert.\n - Die Zähler-Props gehören dem `CounterBehavior` und stehen nicht in der Props-Config der Felder; die Watcher der Felder geben sie an das Behavior weiter.\n - Die Props an `InputFC` folgen der Schlüsselreihenfolge von `InputStateWrapper`. Props, die der Legacy-State nur gesetzt enthielt (`accessKey`, `maxlength`, `placeholder`, `pattern`, `aria-keyshortcuts`), werden nur übergeben, wenn ein Wert gesetzt ist; ein leerer Name wird nicht gerendert. Den Unterschied sieht nur der Hydrate-Snapshot, Jest verwirft leere Attribute.\n - `has-value` ist wie im Legacy-Code ein einfaches Feld ohne Re-Render (#11053).\n - Beim Laden werden Wert und Maximum ohne Zähler-Update übernommen, der Zähler wird in `componentDidLoad` gefüllt.\n - Icons und Smart-Button der Input-Container bildet `getInputAdornments()` (`form-field/adornments.tsx`) für alle migrierten Felder, auch für `kol-input-color`.\n- G2.3: `kol-input-password` auf `BaseTextInputWebComponent`, mit `visibilityToggle` und dem State `passwordVisible`. Der Kompatibilitätszweig `_variant === 'visibility-toggle'` (#10247) entfällt: Legacy verglich den bereits zu einem Array normalisierten `_variant` mit einem String, der Zweig griff also nie. Der G2.0-Snapshot pinnt das. `input-password/controller.ts` bleibt bis G2.4, weil `InputTextController` davon erbt.\n- G2.4: `kol-input-text` auf `BaseTextInputWebComponent`, mit `type` (auch als Root-Klasse), `spellCheck`, `suggestions`, Clear-Button bei `type=\"search\"` und den fünf Selection-Methoden. `has-value` folgt hier wie bisher jeder Wertänderung. Mit dem Feld fällt die Controller-Kette `InputPasswordController → InputTextEmailController → InputTextController` weg.\n- G2.5: `kol-textarea` erbt direkt von `BaseFormFieldWebComponent` und komponiert das `CounterBehavior`; die drei Zähler-Watcher wiederholen die Einzeiler der Textbasis, eine dritte Basisebene ist nicht erlaubt. Übernommen werden die Zeilenberechnung von `_adjustHeight` (wächst nur, #11051), das `setTimeout` in `componentDidLoad` für `_rows` und `style.resize`; `spellCheck` wird gerendert (#10863 wurde in #11073 behoben). Mit dem Feld fallen `CounterDomUpdater`, `TextAreaStateWrapper` und das alte `inputs/TextArea` samt Adapter-Test weg.\n- `CounterBehavior` ersetzt `utils/counter-dom-updater.ts`; das direkte DOM-Update ohne Re-Render bleibt erhalten.\n- textarea erbt direkt von `BaseFormFieldWebComponent` und nutzt das CounterBehavior.\n- Risiken: Selection-API und `_type` search/url/tel von input-text; Clear-Button und Visibility-Toggle; Datalist-IDs; `_adjustHeight`/`_resize` bei textarea.\n- Zusätzliche Abnahme: `input-character-limit` und `input-text.clear-button.e2e` grün; alle 16 React-Routen von input-text pixelgleich.\n\n### G3 – Wertetypen (#9581, #9584, #9578, #9580)\n\nDrei parallele Spuren: a) number → range, b) date, c) file. Die Felder nutzen die Standard-Hülle, müssen aber ihren Wert umwandeln.\n\n- Eigene Input-Props für min/max/step; die vorhandenen Meter-Props (Defaults 0/100) passen nicht.\n- a) Step-Buttons und Feature-Flag `inputNumberButtons`; range mit zwei synchronen Inputs und Suggestions. G3a besteht aus vier PRs:\n\n ```\n G2.5 ─► G3a.0 Testlücken ─► G3a.1 Props + Zahlen-Helfer ─► G3a.2 number ─► G3a.3 range\n ```\n\n - G3a.0: Jest-Snapshots für min/max/step, `_value` als Zahl, `NumberString`, `null` und `0`, die Namen und die Breitenformel von range. Befunde, die die Migration 1:1 übernimmt: #10861 (range klemmt nicht bei einer Grenze 0), #11075 (range synchronisiert beim Ziehen nicht), #11076 (range übernimmt ohne `_value` den Browser-Mittelwert), #11077 (negative und Exponent-Strings werden verworfen), #11053 (`has-value` fehlt bei number für `0`).\n - G3a.1: `inputMinProp`, `inputMaxProp`, `stepProp` und der Zahlenwert in `internal/props/` mit einer Normalisierung, die `validateNumber` 1:1 nachbildet; reine Hilfsfunktionen für den gemerkten Werttyp, das Parsen und die Klemmung von range; `getInputAdornments()` bekommt ein `startAdornment` vor dem linken Icon.\n - G3a.2: `kol-input-number` erbt direkt von `BaseFormFieldWebComponent`. Die Step-Buttons bleiben native `<button>` und folgen bei jedem Render dem Flag `inputNumberButtons`.\n - G3a.3: `kol-input-range` erbt direkt von `BaseFormFieldWebComponent`, mit zwei `InputFC` und dem Datalist neben dem Wrapper.\n - Eine gemeinsame Basis für number und range gibt es nicht: number schreibt `_value` bei jedem `input`, range erst bei `change` und klemmt dabei.\n\n- b) Date↔ISO-Logik aus `input-date/controller.ts` in Hilfsfunktionen, alle 5 `_type`s, Zeitzonen. G3b besteht aus drei PRs:\n\n ```\n G3a.3 ─► G3b.0 Testlücken ─► G3b.1 Props + Datums-Helfer ─► G3b.2 date\n ```\n\n - G3b.0: Jest-Snapshots für alle fünf `_type`s mit Wert, `_min`/`_max`, `_step` bei `time`, einen zum Typ unpassenden Wert, `null` sowie `_readOnly` und `_required`. Werte als `Date` pinnen weiter die e2e-Tests und `controller.spec.ts`, weil ein `Date` im Namen eines Snapshots von der Zeitzone abhängt.\n - G3b.1: der Typ und die Datums-Props (`_min`, `_max`, `_value`, abhängig von `_type` und `_step`) in `internal/props/`; die Umwandlung `Date` → ISO-String, die Kalenderwoche und die Formatprüfung je Typ als reine Hilfsfunktionen, die der Legacy-Controller sofort nutzt.\n - G3b.2: `kol-input-date` erbt direkt von `BaseFormFieldWebComponent`, mit `reset()`, dem Rückschreiben von `_value` beim Blur, wenn der Wert zwischen leer und gesetzt wechselt, Enter-Submit außer bei fokussiertem Kalender-Icon und dem unterdrückten Leerzeichen bei `_readOnly`.\n - Befund: `InputDateController.validateOn` legt einen Wrapper um `_on.onChange` in den State, den nichts liest; die Events rufen das `_on` der Prop. Die Migration übernimmt den Wrapper nicht, das Verhalten bleibt gleich.\n\n- c) FileList, Drag-&-Drop-Modifier, Browse-Button, übertragener Formularwert. G3c besteht aus drei PRs:\n\n ```\n G3b.2 ─► G3c.0 Testlücken ─► G3c.1 accept-Prop + Dateinamen-Helfer ─► G3c.2 file\n ```\n\n - G3c.0: Jest-Snapshots für `_accept`, `_multiple`, `_required`, ein Feld ohne Namen und `_accept` mit `_multiple`, Icons und Smart-Button. e2e für mehrere Dateien, `--has-file` bei Auswahl und `reset()`, den Formularwert nach Auswahl und Drop sowie den Ist-Stand beim Drop: Dateiname ohne `--has-file`, `change` vor `input` (#10865). Befund, den die Migration 1:1 übernimmt: `reset()` wirft bei Formular-Zuordnung einen TypeError (#11110).\n - G3c.1: `acceptProp` in `internal/props/` und ein reiner Helfer für den angezeigten Dateinamen, den die Legacy-Komponente sofort nutzt. `multipleProp` und `requiredProp` gibt es schon.\n - G3c.2: `kol-input-file` erbt direkt von `BaseFormFieldWebComponent`. Der Browse-Button bleibt `KolButtonWcTag`, weil die Themes `.kol-input-container__button .kol-button` als Vorfahr-Beziehung selektieren (G7). Die Drag-Listener hängen dann als JSX-Listener am Container; die Legacy-Komponente hängt sie in `componentDidLoad` an und entfernt sie nie.\n\n- Zusätzliche Abnahme: `table-settings` pixelgleich; `reset()` bei date und file; Flag an und aus im Pixel-Gate.\n\n### G4 – Auswahl-Controls: checkbox → radio (#9576, #9583)\n\nNur diese beiden nutzen den FieldControl-Stack statt InputContainer und teilen `InputCheckboxRadioController`.\n\n- G4 besteht aus fünf PRs:\n\n ```\n G3 ─► G4.0 Testlücken ─► G4.1 options ─► G4.2 FieldControl-/Checkbox-/Radio-FCs + fieldset ─► G4.3 checkbox ─► G4.4 radio\n ```\n\n - G4.0: Snapshots für checkbox (ohne Namen, `_required`, `_value` als String und Objekt, eigene `_icons`, `_labelAlign: 'left'` mit `_hideLabel`, indeterminate als Switch) und radio (ausgewählte Option, ohne Namen, Gruppe `_disabled`, `_required`, `_hideLabel`, Option mit `hint`, Objektwert, Label als Zahl). e2e für die Pfeiltasten-Navigation von radio, `focus()`/`click()` sowie `getValue()`, den `onInput`-Wert `null` beim Abwählen (für `table-settings`) und das Löschen von `_indeterminate` bei checkbox. Befunde, die die Migration 1:1 übernimmt: #11114.\n - G4.1: `options`-Prop und `fillKeyOptionMap` ziehen aus `input-radio/controller.ts` nach `form-field/options.ts`; G5 braucht beides ebenfalls.\n - G4.2: FieldControlFC, CheckboxFC und RadioFC, dazu der `fieldset`-Wurzelknoten: `BemRootNodeFC` und `FormFieldFC` bekommen `component: 'div' | 'fieldset'`, das Label eine `legend`-Variante. Die alten FCs werden Adapter, damit Hydrate-Snapshot und Pixel-Gate die neuen sofort prüfen.\n - G4.3 und G4.4: die beiden Felder erben direkt von `BaseFormFieldWebComponent`; `InputCheckboxRadioController` wird aufgelöst.\n\n- Risiken: Theme-SCSS der Checkbox (300 LOC, verschachtelte Varianten); `indeterminate` nur als Property; Formularwert bei checked/unchecked; Objektwerte, Tastatur- und Fokus-Navigation bei Radio.\n- Zusätzliche Abnahme: alle drei Checkbox-Varianten je Theme; Tastatur-E2E für Radio; `table-settings` pixelgleich.\n\n### G5 – Listen: select → combobox + single-select (#9594, #9569, #9595)\n\n- select: `BaseSelectWebComponent` für `kol-select` und das Übergangs-Tag `kol-select-wc` (DD16, Übergangsmuster `shadow: false`).\n- combobox und single-select: gemeinsame Basis oder ein `ListboxBehavior` für Tastatur, open/close und focusin/out. `@Listen`-Handler folgen der Event-Handler-Policy.\n- Risiken: Options-Sync des versteckten `<select multiple>`; `pagination` hängt am Light DOM von `kol-select-wc`; `:has()`-Selektoren im CustomSuggestions-SCSS.\n- Zusätzliche Abnahme: `pagination` pixelgleich; Tastatur- und Maus-E2E für combobox und single-select; bekannte Bugs bestehen nachweislich unverändert weiter oder wurden vorher gefixt.\n- Schnitt: G5.0 Testlücken → G5.1 select-Fundament (Props, Wert-Helfer, `SelectFC`, Legacy-FCs als Adapter) → G5.2 `kol-select` und `kol-select-wc` → G5.3 `BaseListboxWebComponent` und `kol-combobox` → G5.4 `kol-single-select`.\n- G5.0: Die select-Snapshots registrieren `kol-select` und `kol-select-wc`, damit sie das native Select enthalten. Neue e2e-Tests „Keyboard and mouse“ (combobox, single-select) und „Value“ (select). Befunde in #11124 und #10841.\n- `kol-select` rendert das FC direkt in seinem Shadow DOM, ohne das innere `kol-select-wc`. Diese DOM-Änderung wird in G5.2 einzeln abgenommen. Als eigenständiges Formularfeld setzt `kol-select` `_touched` und `_value` wie alle migrierten Felder; damit ist #11014 behoben. Nach G5.4 überträgt `kol-select` auch einen Einzelwert in `FormData` und in das `_syncValueBySelector`-Ziel (#11015): Ein `<select>`-Ziel erhält je Wert eine gewählte Option, ein anderes Ziel den Wert als String, mit `_multiple` als JSON.\n- `kol-single-select` liest `_value` und `_rows` ungeprüft wie zuvor: Jeder Wert von `_value`, auch `undefined`, ist die Auswahl, und `_rows` ist der CSS-Wert `--visible-options`. Der Abgleich des Eingabetexts mit den Labels beim Verlassen des Felds (#10501, #10617) bleibt bis zu einem eigenen Fix.\n\n### G6 – Rückbau\n\nGelöscht wird, sobald der letzte Import weg ist. Veröffentlichte Schema-Typen bleiben stehen: die `*Watches`-Typen und die `validate*`-Funktionen aus `schema/index.ts` sind Teil der veröffentlichten API (der `react-hook-form-adapter` importiert aus `dist/types/schema`), ihr Entfernen wäre ein eigener Breaking Change. In `functional-components/` bleiben `Heading` (alert, card, collapsible) und `ToastItem` (toaster).\n\n| Zeitpunkt | Was gelöscht wird |\n| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| nach G2 | erledigt in G2: `utils/counter-dom-updater.ts`, `InputPasswordController`, `InputTextEmailController`, `InputTextController`, `TextAreaStateWrapper`, alte `inputs/TextArea` |\n| nach G3a | erledigt in G3a: `InputNumberController`, `InputRangeController`, `InputIconController.isNumberString` |\n| nach G3b | erledigt in G3b: `InputDateController`, `InputIconController.validateNumber`/`parseToNumber` |\n| nach G3c | erledigt in G3c: `InputFileController` |\n| nach G4 | erledigt in G4: `InputCheckboxController`, `InputRadioController`/`InputCheckboxRadioController`, `Checkbox`-/`Radio`-/`FieldControlStateWrapper`, altes `FieldControl`, alte `inputs/Checkbox`/`inputs/Radio` |\n| nach G5 | erledigt in G5.2–G5.4: `SelectController`, `ComboboxController`, `SingleSelectController`, `SelectStateWrapper`, `NativeSelect`/`NativeOption(List)`, alte `CustomSuggestionsOption(sGroup)`; `kol-select-wc` in G7.7, nachdem `kol-pagination` das Select-Feld in G7.6 direkt rendert |\n| final | erledigt: `@deprecated/input/*` (`InputController`, `InputIconController`), `input-adapter-leanup/`, `functional-component-wrappers/` inkl. `getRenderStates`, die Adapter aus G1.3, die alten FormField-/Input-FCs in `functional-components/` (`FormField*`, `InputContainer`, `InputAdornment`, `IconButton`, `inputs/`, `Suggestions`, `Button`) |\n\n### G7 – Folge-Epics (außerhalb dieser Migration)\n\n- ✅ Die Übergangs-Tags (`kol-button-wc`, `kol-link-wc`, `kol-popover-button-wc`, `kol-select-wc`, `kol-dialog-wc`, `kol-alert-wc`, `kol-table-settings-wc`) sind durch die Functional Components und Items ersetzt und gelöscht (G7.1–G7.7, #11167, #11172, #11174–#11178). `kol-tooltip-wc` bleibt als einzige `-wc`-Komponente erhalten: weiterhin deprecated und ausdrücklich nur für DESYBRI.\n- Umstieg auf natives `formAssociated` mit ElementInternals (Verhaltensänderung, eventuell Breaking).\n- BEM-Bereinigung mit CLI-Tasks `ScssRename*` und Migrationsguide für Custom-Themes.\n\n## Offene Fragen für die Detailpläne\n\n1. ~~Sind die Shell-Adapter (alte FC → neue FC) als Zwischenschicht akzeptabel? (G1.3)~~ Entschieden: ja, siehe G1.3.\n2. ~~ID-Strategie: bisherige Erzeugung für Snapshot-Parität oder DD12 `createUniqueId`? (G1.4)~~ Kein Konflikt: Legacy nutzt bereits `createUniqueId` und `createRelatedUniqueId`. Die Basis-ID wird einmal pro Instanz als `@State()` erzeugt.\n3. ~~`_touched` als `@State` oder als Render-Prop? (G1.4)~~ Entschieden: Render-Prop. `_touched` bleibt `@Prop({ mutable: true, reflect: true })`, der Blur-Handler schreibt die Prop (Vorbild `_open` in `kol-details`).\n4. ~~`_on`: eine gemeinsame Callback-Prop oder typisiert pro Feld? (G1.1)~~ Entschieden: gemeinsam, alle Felder deklarieren `InputTypeOnDefault`.\n5. ~~SSR-Absturz von `attachInternals(undefined)` 1:1 übernehmen oder mit eigenem PR über einen Guard absichern? (G1.2)~~ Entschieden: 1:1 übernehmen, Fix als eigener PR nach G1.2 (#11034). Ursache ist nicht ein leeres `@Element()`: In mock-doc greift `instanceof Element` in `findHostWithShadowRoot` nicht. Betroffen sind im SSR die inneren `kol-button-wc`/`kol-popover-button-wc` und mit `serializeShadowRoot: 'scoped'` alle Legacy-Felder.\n6. ~~Verhaltensverträge in Jest oder in Playwright? (G0)~~ Entschieden: Playwright, siehe G0.\n7. ~~Namen der Input-Props für min/max/step. (G3)~~ Entschieden: `inputMinProp`, `inputMaxProp` und `stepProp`, analog zu `horizontalIconsProp` (G1.1).\n8. ~~`kol-select-wc` als Übergangs-Tag behalten oder `pagination` direkt auf das FC umstellen? (G5)~~ Entschieden: `kol-select` rendert das FC direkt. `kol-select-wc` bleibt als Übergangs-Tag für `pagination`, mit derselben Basis; die Ablösung braucht Theme-Änderungen (G7). Umgesetzt in G7.6 und G7.7.\n9. ~~combobox und single-select: gemeinsame DD16-Basis oder `ListboxBehavior`? (G5)~~ Entschieden: gemeinsame Basis `BaseListboxWebComponent extends BaseFormFieldWebComponent`, wie `BaseTextInputWebComponent` in G2.\n10. ~~#10501 und #10617 vor oder nach der Migration fixen? (G5)~~ Entschieden: nach der Migration, als eigener PR auf dem migrierten Code. Die Migration übernimmt das Verhalten 1:1.\n\n## Grundlagen\n\n- `packages/components/src/components/_skeleton/ARC42.md`\n- Skill `.claude/skills/migrate-to-skeleton/` (inkl. `reference/patterns.md`, `reference/pitfalls.md`)\n- Skill `.claude/skills/zero-visual-delta-handoff/`\n",
417
+ "code": "# Migrationsplan: Formularfelder auf Skeleton\n\nÜbergreifender Plan für die Skeleton-Migration der 14 Formularfelder von `kol-combobox` bis `kol-textarea` (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.\n\nStand: 27.09.2026, `@public-ui/components` 4.5.0-rc.0.\n\n## Ausgangslage\n\nVor der Migration lief keines der 14 Felder auf Skeleton. Der Legacy-Stack besteht aus:\n\n- Controller-Kette `AssociatedInputController → ControlledInputController → InputController → InputIconController → Feld-Controller`\n- State-Wrapper in `functional-component-wrappers/`, die die alten FCs in `functional-components/` rendern\n- Validatoren aus `schema/props/`\n\nAus dem Formularumfeld ist bisher nur `kol-form` auf Skeleton umgestellt.\n\n| Feld | LOC `shadow.tsx` | Render-Stack heute | Besonderheit |\n| -------------------- | --------------------------- | ------------------------------------------- | --------------------------------------------------------------- |\n| `kol-input-color` | 380 | FormField + InputContainer + Input („Trio\") | dünnstes Feld, kein `_required` |\n| `kol-input-email` | 489 | Trio | Controller erbt von Text → Password, Counter |\n| `kol-input-password` | 511 | Trio + IconButton (`KolButtonWcTag`) | `_visibilityToggle`, Basisklasse für Text und Email |\n| `kol-input-text` | 620 | Trio + Clear-Button | `_type`, Selection-API-Methoden |\n| `kol-textarea` | 498 | FormField + InputContainer + TextArea | `_adjustHeight`, `_resize`, `_rows`, Counter |\n| `kol-input-number` | 551 | Trio + Step-Buttons | Feature-Flag `inputNumberButtons`, genutzt von `table-settings` |\n| `kol-input-range` | 499 | 2× Input (range + number) + Suggestions | min/max/step, zwei synchrone Inputs |\n| `kol-input-date` | 513 (+ 219 Controller) | Trio | Date↔ISO, 5 `_type`s, `reset()` |\n| `kol-input-file` | 450 | Trio + Browse-Button (`KolButtonWcTag`) | kein `_value`, FileList, `_accept`, Drag & Drop, `reset()` |\n| `kol-input-checkbox` | 457 | FormField + FieldControl + Checkbox | Varianten default/switch/button, genutzt von `table-settings` |\n| `kol-input-radio` | 458 | FormField (fieldset) + FieldControl + Radio | `_options`, `_orientation`, alte Utils `element-click`/`-focus` |\n| `kol-select` | 222 + 404 (`kol-select-wc`) | FormField + InputContainer + NativeSelect | `pagination` rendert `kol-select-wc` direkt |\n| `kol-combobox` | 756 | Trio + CustomSuggestions + `@Listen` | Listbox, nahezu Zwilling von single-select |\n| `kol-single-select` | 849 | Trio + CustomSuggestions + `@Listen` | größtes Feld, offene Bugs #10501/#10617 |\n\n## Rahmenbedingungen\n\n- **Zero visual delta, BEM bleibt.** DOM und Klassen (`.kol-form-field`, `.kol-input-container`, `.kol-field-control` …) bleiben byte-identisch. Themes werden nicht angefasst, es gibt keinen CLI-/SCSS-Migrations-Task. Das Pixel-Gate verlangt 0 Diffs pro Theme. Die gemeinsame Wurzel `kol-form-field` mit dem Komponentenblock als zusätzlicher Klasse ist ein zulässiges Skeleton-Muster (ARC42-SKELETON, „Shared Shell Root of the Form Fields“, Designentscheidung 19); der Komponentenblock wird in `schema/bem-registry.ts` registriert.\n- **Formular-Anbindung 1:1 als Behavior.** Die heutige Semantik (versteckte native Elemente im Light DOM, `_syncValueBySelector`, `ariaDetails` über `attachInternals`) wandert aus der Controller-Kette in ein wiederverwendbares `FormAssociationBehavior`, das auch `kol-button` nutzt. Einen Umstieg auf natives `formAssociated` gibt es in dieser Migration nicht.\n- **Identische öffentliche API.** Gleiche `@Prop`/`@Method`-Member, Alias-Typen, Defaults und JSDoc. Die Oberfläche ist vor der Migration in `_skeleton/public-api/<komponente>.spec.ts` festgenagelt.\n\n## Leitplanken\n\n- **Strangler statt Big Bang.** Der neue Stack entsteht unter `internal/functional-components/form-field/` neben dem alten. Ein Legacy-Modul wird in dem PR gelöscht, der seinen letzten Import entfernt.\n- **Keine Bugfixes in Migrations-PRs.** Bekannte Fehler (z. B. #10501, #10617) bekommen eigene PRs, vor oder nach der Migration.\n- **Innere Tags bleiben.** `KolButtonWcTag` (IconButton, Clear-, Browse- und Visibility-Button) und `KolPopoverButtonWcTag` (Label-`_infoPopover`) bleiben wegen Zero-Delta stehen. Das ist eine begründete Ausnahme nach Fallstrick 8 im Skill `migrate-to-skeleton`.\n- **Grenze von DD16.** Stencil liest Decorators nur aus der konkreten Klasse. Alle `@Prop`/`@Watch`/`@Method` samt JSDoc bleiben in jeder Komponente, Basisklassen bündeln nur Logik. Höchstens zwei Ebenen unter `BaseWebComponent`.\n- **Basisklasse nach G1 eingefroren.** Änderungen an `BaseFormFieldWebComponent` kommen nur als eigenes PR, mit Pixel-Gate über alle bereits migrierten Felder.\n- **Konfliktstellen.** `internal/props/index.ts`, `schema/bem-registry.ts` und die Pin-Dateien: nur anhängen, Reihenfolge zwischen den Spuren absprechen.\n\n### Abnahme-Gates je Komponenten-PR\n\n1. Der Public-API-Pin ist unverändert und zeigt jetzt auf `component.tsx`. Die Klasse implementiert `*Props`.\n2. Die Jest-`.snap`-Dateien sind unverändert.\n3. `node scripts/snapshots-docker.mjs <theme> --check` meldet 0 Diffs für default, bwst, desy, kern und ecl (ec/eu).\n4. Die Verhaltensverträge aus G0 sind grün.\n5. Die geteilten E2E-Helfer `src/e2e/{input-msg,input-value-reflection,input-character-limit}.ts` sind grün.\n6. Keine Imports mehr aus `@deprecated/input`, `input-adapter-leanup`, `functional-component-wrappers` oder den alten `functional-components/*`.\n7. `form.e2e` ist grün: Ein Klick in der Fehlerliste fokussiert das Feld über seinen `focus()`.\n\n## Reihenfolge und Abhängigkeiten\n\n```\nG0 ─► G1.1 ─┬─► G1.2 ──┐\n └─► G1.3 ──┴─► G1.4 (Pilot input-color)\n ├─► G2 Textfelder (Spur A)\n ├─► G3 a | b | c (Spur B)\n └─► G4-Vorbereitung ─► G4 ─► G5 (Spur C)\nRückbau-Inkremente am Ende jeder Gruppe; finaler Rückbau (G6) nach G2–G5\n```\n\n## Gruppen\n\n### G0 – Absicherung\n\nKein Produktivcode, Voraussetzung für alles. Die Gates greifen nur, wenn vorher festgehalten ist, was „unverändert\" heißt: API, Verhalten und Pixel.\n\n- ✅ Public-API-Pins für alle 14 Tags und `kol-select-wc` (als interner Vertrag), zunächst gegen `shadow.tsx`. Jede Komponente hat eine eigene Datei unter `_skeleton/public-api/`, damit parallele Spuren keine Merge-Konflikte bekommen.\n- ✅ Verhaltensverträge pro Feld: Reihenfolge und Payload von `kolChange`/`kolInput`/`kolFocus`/`kolBlur`/`kolKeydown`/`kolClick` und der `_on`-Callbacks; `FormData` eines nativen `<form>` für Checkbox, `select` multiple, File und Radio mit Objektwerten; `_syncValueBySelector`; `_touched` nach Blur. Die Verträge sind Playwright-Tests (`*.e2e.ts`), weil versteckte Light-DOM-Elemente, `attachInternals`, `FormData` sowie Fokus und Tastatur nur im echten Browser verlässlich prüfbar sind. Sie nutzen die Helfer aus `src/e2e/`. Reine Umrechnungen ohne Browserverhalten (z. B. Date↔ISO in G3) werden als Jest-Tests der Hilfsfunktionen geprüft.\n - Der gemeinsame Helfer `testInputBehaviorContract` in `src/e2e/input-behavior-contract.ts` zeichnet Events und Callbacks auf; jedes Feld pinnt darin sein heutiges Verhalten. Alle 14 Felder sind gepinnt, dazu die Varianten Radio mit Objektwerten und `kol-select` mit `_multiple` (Option `variant`).\n - Befunde aus den Verträgen: Die gepinnten Abläufe beschreiben den heutigen Stand, auch wo er inkonsistent ist. Korrekturen kommen als eigene PRs nach der jeweiligen Migration.\n - Standard (G1.4, alle Felder außer den unten genannten Abweichungen): Je Aktion kommt zuerst das KoliBri-Event am Host, dann der `_on`-Callback, dann das native Event. Natives `input`/`change` endet an der Shadow-Grenze.\n - Startwert ohne Vorgabe: `kol-input-color` `#000000` (aus dem inneren Input in `componentDidLoad`), `kol-input-range` `50`, `kol-input-checkbox` `true`, `kol-input-radio` und `kol-single-select` `null`, alle anderen `undefined`.\n - G3: Payloads sind typisiert – number und range liefern Zahlen, date den ISO-String, file eine `FileList`. Für file bleibt ein Text-Input als `_syncValueBySelector`-Ziel leer.\n - G4: checkbox und radio senden kein KoliBri-`click` und keinen `onClick` (`onClick: undefined` in `shadow.tsx`). Stattdessen erreicht das native `click` den Host vor `input`/`change`.\n - G5: `kol-single-select` sendet beim Blur zuerst das native Event, dann das KoliBri-Event und den Callback. `kol-select` setzt `_touched` am eigenen Host nicht, das innere `kol-select-wc` hält den Zustand. Außerdem überträgt `kol-select` einen Einzelwert weder in `FormData` noch in das `_syncValueBySelector`-Ziel, weil das versteckte `<select multiple>` nur Array-Werte übernimmt. Mit `_multiple` stehen alle gewählten Werte in `FormData`. Issues: #11014 (`_touched`, behoben in G5.2), #11015 (Einzelwert, behoben nach G5.4).\n - Radio mit Objektwerten liefert das Objekt als Payload und überträgt es als JSON-String in `FormData` und an `_syncValueBySelector`.\n - Formular-Anbindung heute: Das versteckte Element im Light DOM entsteht nur mit `register(…, { reflectInputValues: true })`, seinen `name` setzt der Controller nur im Experimental-Mode. Nur mit beidem steht das Feld in `FormData`. Der Vertrag pinnt alle drei Fälle, der Test ruft `register` dafür aus dem Build unter Test auf.\n- ✅ Visual-Samples ergänzen für msg, hint, disabled, hideLabel, infoPopover, Counter, Icons, `inputNumberButtons` an/aus und die Checkbox-Varianten. Neue Samples erzeugen neue Baselines und gehören in ein eigenes PR vor der ersten Migration.\n - Vorhanden: msg, hint, disabled, hideLabel, infoPopover und Icons für alle 14 Felder über `partials/cases.tsx`/`variants.tsx`, Counter bei `input-text` und `textarea`, Checkbox-Varianten `basic`/`button`/`switch`.\n - `inputNumberButtons` setzt das Theme (`theme-default` `'show'`, `theme-kern` `'hide'`); die bestehenden `input-number`-Baselines decken damit beide Zustände ab.\n - Ergänzt in #11017: Counter-Routen für `kol-input-email` und `kol-input-password`, Hint-Block für `kol-input-number`.\n- ✅ Toten Code löschen: `functional-components/inputs/Combobox/Combobox.tsx`.\n\n### G1 – Fundament + Pilot `kol-input-color` (#9673, #9577)\n\nAlle 14 Felder teilen Basis-Props, die Label/Hint/Msg-Hülle, die Formular-Anbindung und die Event-Logik. Das wird einmal gebaut und am dünnsten Feld geprüft, damit die Basisklasse an einem echten Fall entsteht. G1 besteht aus sechs PRs: G1.0 #11037, G1.1 #11038, G1.2 #11044, G1.3a #11045, G1.3b #11046 und G1.4 #11049. Alle sind gemergt.\n\n```\nG1.0 Testlücken ───────────────┬──────────────────────────────────────────────┐\nG1.1 Props ─┬─► G1.2 FormAssociationBehavior (+ kol-button) ─► SSR-Fix (eigener PR)\n │ (braucht G1.0 und G1.1) │\n └─► G1.3a FormField ─► G1.3b Container/Input ──────────────────────┴─► G1.4 Basis + kol-input-color\n```\n\n0. **Testlücken** (nur Tests):\n - Formular-Anbindung von `kol-button` gepinnt. Es entsteht kein verstecktes Formularelement, weil der Adapter in `button/base.tsx` `_name` bei der Konstruktion nicht kennt (#11036); `_syncValueBySelector` wirkt im Experimental-Mode.\n - Gate 7 mit einem `kol-input-color` als Ziel der Fehlerliste.\n - Tooltip bei `_hideLabel` für `kol-input-color`. Befund: Hat das Feld den Fokus, schließt Escape den Tooltip nicht. Das Feld sendet sein eigenes `keydown`-CustomEvent am Host, das vor der nativen Taste am Dokument ankommt und den einmaligen Escape-Listener des Tooltips verbraucht (#11032, verwandt #11033).\n - Jest-Snapshots aller Felder zusätzlich mit `_hideLabel`, `_infoPopover`, sichtbarer Msg und `_variant`.\n1. **Basis-Props** in `internal/props/`: ariaDetails, autoComplete, hideMsg, hint, `horizontalIconsProp` (Icons-Objekt der Inputs, `icons.ts` bleibt unverändert), infoPopover, `inputCallbacksProp` (`_on`), msg, readOnly, required, suggestions, syncValueBySelector (nur für das Behavior), touched und der String-Wert. `tooltipAlignProp` wird wiederverwendet, der Feld-Default `'top'` im `apply` neu gesetzt. Der veröffentlichte Typ `FormFieldLabelInfoPopoverProps` zieht in einem Schritt für alle Felder nach `schema/props/`; ein teilweiser Umzug würde in `components.d.ts` einen Alias `…1` erzeugen.\n2. **`FormAssociationBehavior`**: übernimmt `input-adapter-leanup/associated.controller.ts` 1:1, einschließlich der späten Host-Zuweisung im Konstruktor. `AssociatedInputController` wird zur Fassade über das Behavior, damit die G0-Verträge es sofort für alle Felder prüfen. `button/base.tsx` wird im selben PR umgestellt; der Button-Pin bleibt unverändert.\n3. **Shell-FCs** unter `internal/functional-components/form-field/`, nur für die Hülle von `kol-input-color`: G1.3a FormField (Label, Hint, Msg, Counter, Tooltip, Zeichengrenzen-Hinweis) mit dem ARIA-Helfer aus `getRenderStates`, G1.3b InputContainer mit Adornments, IconButton, Input und Suggestions. Neue Blöcke in `schema/bem-registry.ts`. Die alten FCs werden Adapter auf die neuen, damit Hydrate-Snapshot und Pixel-Gate die Hülle sofort über alle Felder prüfen. TextArea kommt in G2, FieldControl/Checkbox/Radio in G4, NativeSelect/Option(List)/CustomSuggestions in G5. Die `fieldset`-Wurzel von radio bleibt bis G4 auf dem alten Pfad, weil `BemRootNodeFC` nur `div` rendert.\n4. **`BaseFormFieldWebComponent`** (DD16): `apply*` der Basis-Props, ein eigenes `TooltipBehavior` pro Instanz statt der modulglobalen Map in `FormField.tsx`, Formular-Anbindung, Event-Behandlung als Ersatz für `InputController` (Reihenfolge: KoliBri-Event, dann Callback) und Render-Helfer. Damit wird `kol-input-color` migriert.\n - Die Basis ist generisch über die Feld-API. Sie greift über einen dokumentierten Self-Cast (`shared`) auf die Basis-Props zu und liefert die FormField-Props mit `getFormFieldProps()`. Gerendert wird in der konkreten Klasse, wie bei `BaseButtonWebComponent`.\n - Die Props an `InputFC` bildet die konkrete Klasse in der Schlüsselreihenfolge der alten State-Wrapper. Props, die der Legacy-State nur bei gesetztem Wert enthielt, zum Beispiel `accessKey` und `aria-keyshortcuts`, übergibt sie nur, wenn ein Wert gesetzt ist. Nur so bleiben die Attributreihenfolge im Hydrate-Snapshot und das DOM unverändert.\n - `_label={false}` bleibt wie bisher der Expert-Slot (`''`). `labelWithExpertSlotProp` allein würde daraus den String `'false'` machen.\n\nEntscheidungen:\n\n- Die Basis-Config enthält nur Props, die alle 14 Felder identisch haben: ariaDetails, disabled, hideLabel, hideMsg, hint, infoPopover, label, msg, name, on, tooltipAlign, touched. `WebComponentInterface` verlangt für jede Config-Prop einen Watcher.\n- Die Basisklasse ist generisch über die Feld-API. TypeScript löst `ResolvedProps<Api>` für ein generisches `Api` nicht auf, deshalb greift sie über einen einzigen, dokumentierten Self-Cast auf die Basis-Props zu.\n- Bewusste Abweichungen der Prop-Factory, wie in allen bisherigen Skeleton-Migrationen: `undefined` führt zum Default statt den alten Wert zu behalten, `normalizeBoolean` akzeptiert `'true'`/`'false'`, ungültige Werte werden verworfen.\n- `data-testid=\"input-counter\"`/`\"input-counter-aria\"` bleiben bis G2, weil `e2e/input-character-limit.ts` sie braucht und der DOM byte-gleich bleiben muss.\n\nRisiken: Zusammenbau von `aria-describedby` (hint, msg, Counter, Hinweis zur Zeichengrenze; heutige Eigenheiten in #11035); Attribut- und Klassenreihenfolge im Hydrate-Snapshot; die beiden Fokus-Flags aus Controller und Komponente; `attachInternals(undefined)` bei SSR/Hydrate.\n\n### G2 – Textfelder: email → password → text, danach textarea (#9579, #9582, #9585, #9602)\n\nDie vier Felder hängen heute in der Kette `InputPasswordController → InputTextEmailController → InputText/InputEmail` und teilen placeholder, autoComplete, maxLength/hasCounter/maxLengthBehavior und den Counter. pattern haben nur die drei Inputs. `spellCheck` rendern input-text und textarea (#10863 wurde in #11073 behoben).\n\nG2 besteht aus sechs PRs:\n\n```\nG2.0 Testlücken (nur Tests) ────────────────────────────────────────────────────────┐\nG1.4 ─► G2.1 Props + CounterBehavior + TextAreaFC ─► G2.2 Basis + email ─► G2.3 password ─► G2.4 text ─► G2.5 textarea\n```\n\n- G2.0: Jest-Snapshots für Zähler, Zeichengrenze, Clear-Button, Visibility-Toggle, `_multiple`, `_pattern`, `_required` und `_resize`. Bisher pinnt kein Snapshot diese Fälle. Befunde, die die Migration 1:1 übernimmt: #11051 (`_adjustHeight` schrumpft nicht), #11052 (Zähler bei `_hasCounter`/`_maxLengthBehavior` zur Laufzeit), #11053 (`has-value` uneinheitlich), #11054 (devHint zu `_autoComplete`). Der Befund #10863 (`spellCheck`) wurde in #11073 behoben.\n- G2.1: Props der Textfelder in `internal/props/`; `CounterBehavior` unter `internal/functional-components/counter/` (besitzt `hasCounter`, `maxLength` und `maxLengthBehavior`, `CounterDomUpdater` ist bis G2.5 Fassade darüber); `TextAreaFC` mit dem neuen Block `kol-textarea` und das alte `inputs/TextArea` als Adapter; `getFormFieldProps()` der Basis reicht zusätzlich `required`, `readOnly`, `maxLength` und `counter` durch.\n- G2.2: `BaseTextInputWebComponent` (`internal/functional-components/text-input/`) für email, password und text, damit wird `kol-input-email` migriert.\n - Die Zähler-Props gehören dem `CounterBehavior` und stehen nicht in der Props-Config der Felder; die Watcher der Felder geben sie an das Behavior weiter.\n - Die Props an `InputFC` folgen der Schlüsselreihenfolge von `InputStateWrapper`. Props, die der Legacy-State nur gesetzt enthielt (`accessKey`, `maxlength`, `placeholder`, `pattern`, `aria-keyshortcuts`), werden nur übergeben, wenn ein Wert gesetzt ist; ein leerer Name wird nicht gerendert. Den Unterschied sieht nur der Hydrate-Snapshot, Jest verwirft leere Attribute.\n - `has-value` ist wie im Legacy-Code ein einfaches Feld ohne Re-Render (#11053).\n - Beim Laden werden Wert und Maximum ohne Zähler-Update übernommen, der Zähler wird in `componentDidLoad` gefüllt.\n - Icons und Smart-Button der Input-Container bildet `getInputAdornments()` (`form-field/adornments.tsx`) für alle migrierten Felder, auch für `kol-input-color`.\n- G2.3: `kol-input-password` auf `BaseTextInputWebComponent`, mit `visibilityToggle` und dem State `passwordVisible`. Der Kompatibilitätszweig `_variant === 'visibility-toggle'` (#10247) entfällt: Legacy verglich den bereits zu einem Array normalisierten `_variant` mit einem String, der Zweig griff also nie. Der G2.0-Snapshot pinnt das. `input-password/controller.ts` bleibt bis G2.4, weil `InputTextController` davon erbt.\n- G2.4: `kol-input-text` auf `BaseTextInputWebComponent`, mit `type` (auch als Root-Klasse), `spellCheck`, `suggestions`, Clear-Button bei `type=\"search\"` und den fünf Selection-Methoden. `has-value` folgt hier wie bisher jeder Wertänderung. Mit dem Feld fällt die Controller-Kette `InputPasswordController → InputTextEmailController → InputTextController` weg.\n- G2.5: `kol-textarea` erbt direkt von `BaseFormFieldWebComponent` und komponiert das `CounterBehavior`; die drei Zähler-Watcher wiederholen die Einzeiler der Textbasis, eine dritte Basisebene ist nicht erlaubt. Übernommen werden die Zeilenberechnung von `_adjustHeight` (wächst nur, #11051), das `setTimeout` in `componentDidLoad` für `_rows` und `style.resize`; `spellCheck` wird gerendert (#10863 wurde in #11073 behoben). Mit dem Feld fallen `CounterDomUpdater`, `TextAreaStateWrapper` und das alte `inputs/TextArea` samt Adapter-Test weg.\n- `CounterBehavior` ersetzt `utils/counter-dom-updater.ts`; das direkte DOM-Update ohne Re-Render bleibt erhalten.\n- textarea erbt direkt von `BaseFormFieldWebComponent` und nutzt das CounterBehavior.\n- Risiken: Selection-API und `_type` search/url/tel von input-text; Clear-Button und Visibility-Toggle; Datalist-IDs; `_adjustHeight`/`_resize` bei textarea.\n- Zusätzliche Abnahme: `input-character-limit` und `input-text.clear-button.e2e` grün; alle 16 React-Routen von input-text pixelgleich.\n\n### G3 – Wertetypen (#9581, #9584, #9578, #9580)\n\nDrei parallele Spuren: a) number → range, b) date, c) file. Die Felder nutzen die Standard-Hülle, müssen aber ihren Wert umwandeln.\n\n- Eigene Input-Props für min/max/step; die vorhandenen Meter-Props (Defaults 0/100) passen nicht.\n- a) Step-Buttons und Feature-Flag `inputNumberButtons`; range mit zwei synchronen Inputs und Suggestions. G3a besteht aus vier PRs:\n\n ```\n G2.5 ─► G3a.0 Testlücken ─► G3a.1 Props + Zahlen-Helfer ─► G3a.2 number ─► G3a.3 range\n ```\n\n - G3a.0: Jest-Snapshots für min/max/step, `_value` als Zahl, `NumberString`, `null` und `0`, die Namen und die Breitenformel von range. Befunde, die die Migration 1:1 übernimmt: #10861 (range klemmt nicht bei einer Grenze 0), #11075 (range synchronisiert beim Ziehen nicht), #11076 (range übernimmt ohne `_value` den Browser-Mittelwert), #11077 (negative und Exponent-Strings werden verworfen), #11053 (`has-value` fehlt bei number für `0`).\n - G3a.1: `inputMinProp`, `inputMaxProp`, `stepProp` und der Zahlenwert in `internal/props/` mit einer Normalisierung, die `validateNumber` 1:1 nachbildet; reine Hilfsfunktionen für den gemerkten Werttyp, das Parsen und die Klemmung von range; `getInputAdornments()` bekommt ein `startAdornment` vor dem linken Icon.\n - G3a.2: `kol-input-number` erbt direkt von `BaseFormFieldWebComponent`. Die Step-Buttons bleiben native `<button>` und folgen bei jedem Render dem Flag `inputNumberButtons`.\n - G3a.3: `kol-input-range` erbt direkt von `BaseFormFieldWebComponent`, mit zwei `InputFC` und dem Datalist neben dem Wrapper.\n - Eine gemeinsame Basis für number und range gibt es nicht: number schreibt `_value` bei jedem `input`, range erst bei `change` und klemmt dabei.\n\n- b) Date↔ISO-Logik aus `input-date/controller.ts` in Hilfsfunktionen, alle 5 `_type`s, Zeitzonen. G3b besteht aus drei PRs:\n\n ```\n G3a.3 ─► G3b.0 Testlücken ─► G3b.1 Props + Datums-Helfer ─► G3b.2 date\n ```\n\n - G3b.0: Jest-Snapshots für alle fünf `_type`s mit Wert, `_min`/`_max`, `_step` bei `time`, einen zum Typ unpassenden Wert, `null` sowie `_readOnly` und `_required`. Werte als `Date` pinnen weiter die e2e-Tests und `controller.spec.ts`, weil ein `Date` im Namen eines Snapshots von der Zeitzone abhängt.\n - G3b.1: der Typ und die Datums-Props (`_min`, `_max`, `_value`, abhängig von `_type` und `_step`) in `internal/props/`; die Umwandlung `Date` → ISO-String, die Kalenderwoche und die Formatprüfung je Typ als reine Hilfsfunktionen, die der Legacy-Controller sofort nutzt.\n - G3b.2: `kol-input-date` erbt direkt von `BaseFormFieldWebComponent`, mit `reset()`, dem Rückschreiben von `_value` beim Blur, wenn der Wert zwischen leer und gesetzt wechselt, Enter-Submit außer bei fokussiertem Kalender-Icon und dem unterdrückten Leerzeichen bei `_readOnly`.\n - Befund: `InputDateController.validateOn` legt einen Wrapper um `_on.onChange` in den State, den nichts liest; die Events rufen das `_on` der Prop. Die Migration übernimmt den Wrapper nicht, das Verhalten bleibt gleich.\n\n- c) FileList, Drag-&-Drop-Modifier, Browse-Button, übertragener Formularwert. G3c besteht aus drei PRs:\n\n ```\n G3b.2 ─► G3c.0 Testlücken ─► G3c.1 accept-Prop + Dateinamen-Helfer ─► G3c.2 file\n ```\n\n - G3c.0: Jest-Snapshots für `_accept`, `_multiple`, `_required`, ein Feld ohne Namen und `_accept` mit `_multiple`, Icons und Smart-Button. e2e für mehrere Dateien, `--has-file` bei Auswahl und `reset()`, den Formularwert nach Auswahl und Drop sowie den Ist-Stand beim Drop: Dateiname ohne `--has-file`, `change` vor `input` (#10865). Befund, den die Migration 1:1 übernimmt: `reset()` wirft bei Formular-Zuordnung einen TypeError (#11110).\n - G3c.1: `acceptProp` in `internal/props/` und ein reiner Helfer für den angezeigten Dateinamen, den die Legacy-Komponente sofort nutzt. `multipleProp` und `requiredProp` gibt es schon.\n - G3c.2: `kol-input-file` erbt direkt von `BaseFormFieldWebComponent`. Der Browse-Button bleibt `KolButtonWcTag`, weil die Themes `.kol-input-container__button .kol-button` als Vorfahr-Beziehung selektieren (G7). Die Drag-Listener hängen dann als JSX-Listener am Container; die Legacy-Komponente hängt sie in `componentDidLoad` an und entfernt sie nie.\n\n- Zusätzliche Abnahme: `table-settings` pixelgleich; `reset()` bei date und file; Flag an und aus im Pixel-Gate.\n\n### G4 – Auswahl-Controls: checkbox → radio (#9576, #9583)\n\nNur diese beiden nutzen den FieldControl-Stack statt InputContainer und teilen `InputCheckboxRadioController`.\n\n- G4 besteht aus fünf PRs:\n\n ```\n G3 ─► G4.0 Testlücken ─► G4.1 options ─► G4.2 FieldControl-/Checkbox-/Radio-FCs + fieldset ─► G4.3 checkbox ─► G4.4 radio\n ```\n\n - G4.0: Snapshots für checkbox (ohne Namen, `_required`, `_value` als String und Objekt, eigene `_icons`, `_labelAlign: 'left'` mit `_hideLabel`, indeterminate als Switch) und radio (ausgewählte Option, ohne Namen, Gruppe `_disabled`, `_required`, `_hideLabel`, Option mit `hint`, Objektwert, Label als Zahl). e2e für die Pfeiltasten-Navigation von radio, `focus()`/`click()` sowie `getValue()`, den `onInput`-Wert `null` beim Abwählen (für `table-settings`) und das Löschen von `_indeterminate` bei checkbox. Befunde, die die Migration 1:1 übernimmt: #11114.\n - G4.1: `options`-Prop und `fillKeyOptionMap` ziehen aus `input-radio/controller.ts` nach `form-field/options.ts`; G5 braucht beides ebenfalls.\n - G4.2: FieldControlFC, CheckboxFC und RadioFC, dazu der `fieldset`-Wurzelknoten: `BemRootNodeFC` und `FormFieldFC` bekommen `component: 'div' | 'fieldset'`, das Label eine `legend`-Variante. Die alten FCs werden Adapter, damit Hydrate-Snapshot und Pixel-Gate die neuen sofort prüfen.\n - G4.3 und G4.4: die beiden Felder erben direkt von `BaseFormFieldWebComponent`; `InputCheckboxRadioController` wird aufgelöst.\n\n- Risiken: Theme-SCSS der Checkbox (300 LOC, verschachtelte Varianten); `indeterminate` nur als Property; Formularwert bei checked/unchecked; Objektwerte, Tastatur- und Fokus-Navigation bei Radio.\n- Zusätzliche Abnahme: alle drei Checkbox-Varianten je Theme; Tastatur-E2E für Radio; `table-settings` pixelgleich.\n\n### G5 – Listen: select → combobox + single-select (#9594, #9569, #9595)\n\n- select: `BaseSelectWebComponent` für `kol-select` und das Übergangs-Tag `kol-select-wc` (DD16, Übergangsmuster `shadow: false`).\n- combobox und single-select: gemeinsame Basis oder ein `ListboxBehavior` für Tastatur, open/close und focusin/out. `@Listen`-Handler folgen der Event-Handler-Policy.\n- Risiken: Options-Sync des versteckten `<select multiple>`; `pagination` hängt am Light DOM von `kol-select-wc`; `:has()`-Selektoren im CustomSuggestions-SCSS.\n- Zusätzliche Abnahme: `pagination` pixelgleich; Tastatur- und Maus-E2E für combobox und single-select; bekannte Bugs bestehen nachweislich unverändert weiter oder wurden vorher gefixt.\n- Schnitt: G5.0 Testlücken → G5.1 select-Fundament (Props, Wert-Helfer, `SelectFC`, Legacy-FCs als Adapter) → G5.2 `kol-select` und `kol-select-wc` → G5.3 `BaseListboxWebComponent` und `kol-combobox` → G5.4 `kol-single-select`.\n- G5.0: Die select-Snapshots registrieren `kol-select` und `kol-select-wc`, damit sie das native Select enthalten. Neue e2e-Tests „Keyboard and mouse“ (combobox, single-select) und „Value“ (select). Befunde in #11124 und #10841.\n- `kol-select` rendert das FC direkt in seinem Shadow DOM, ohne das innere `kol-select-wc`. Diese DOM-Änderung wird in G5.2 einzeln abgenommen. Als eigenständiges Formularfeld setzt `kol-select` `_touched` und `_value` wie alle migrierten Felder; damit ist #11014 behoben. Nach G5.4 überträgt `kol-select` auch einen Einzelwert in `FormData` und in das `_syncValueBySelector`-Ziel (#11015): Ein `<select>`-Ziel erhält je Wert eine gewählte Option, ein anderes Ziel den Wert als String, mit `_multiple` als JSON.\n- `kol-single-select` liest `_value` und `_rows` ungeprüft wie zuvor: Jeder Wert von `_value`, auch `undefined`, ist die Auswahl, und `_rows` ist der CSS-Wert `--visible-options`. Der Abgleich des Eingabetexts mit den Labels beim Verlassen des Felds (#10501, #10617) bleibt bis zu einem eigenen Fix.\n\n### G6 – Rückbau\n\nGelöscht wird, sobald der letzte Import weg ist. Veröffentlichte Schema-Typen bleiben stehen: die `*Watches`-Typen und die `validate*`-Funktionen aus `schema/index.ts` sind Teil der veröffentlichten API (der `react-hook-form-adapter` importiert aus `dist/types/schema`), ihr Entfernen wäre ein eigener Breaking Change. In `functional-components/` bleiben `Heading` (alert, card, collapsible) und `ToastItem` (toaster).\n\n| Zeitpunkt | Was gelöscht wird |\n| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| nach G2 | erledigt in G2: `utils/counter-dom-updater.ts`, `InputPasswordController`, `InputTextEmailController`, `InputTextController`, `TextAreaStateWrapper`, alte `inputs/TextArea` |\n| nach G3a | erledigt in G3a: `InputNumberController`, `InputRangeController`, `InputIconController.isNumberString` |\n| nach G3b | erledigt in G3b: `InputDateController`, `InputIconController.validateNumber`/`parseToNumber` |\n| nach G3c | erledigt in G3c: `InputFileController` |\n| nach G4 | erledigt in G4: `InputCheckboxController`, `InputRadioController`/`InputCheckboxRadioController`, `Checkbox`-/`Radio`-/`FieldControlStateWrapper`, altes `FieldControl`, alte `inputs/Checkbox`/`inputs/Radio` |\n| nach G5 | erledigt in G5.2–G5.4: `SelectController`, `ComboboxController`, `SingleSelectController`, `SelectStateWrapper`, `NativeSelect`/`NativeOption(List)`, alte `CustomSuggestionsOption(sGroup)`; `kol-select-wc` in G7.7, nachdem `kol-pagination` das Select-Feld in G7.6 direkt rendert |\n| final | erledigt: `@deprecated/input/*` (`InputController`, `InputIconController`), `input-adapter-leanup/`, `functional-component-wrappers/` inkl. `getRenderStates`, die Adapter aus G1.3, die alten FormField-/Input-FCs in `functional-components/` (`FormField*`, `InputContainer`, `InputAdornment`, `IconButton`, `inputs/`, `Suggestions`, `Button`) |\n\n### G7 – Folge-Epics (außerhalb dieser Migration)\n\n- ✅ Die Übergangs-Tags (`kol-button-wc`, `kol-link-wc`, `kol-popover-button-wc`, `kol-select-wc`, `kol-dialog-wc`, `kol-alert-wc`, `kol-table-settings-wc`) sind durch die Functional Components und Items ersetzt und gelöscht (G7.1–G7.7, #11167, #11172, #11174–#11178). `kol-tooltip-wc` bleibt als einzige `-wc`-Komponente erhalten: weiterhin deprecated und ausdrücklich nur für DESYBRI.\n- Umstieg auf natives `formAssociated` mit ElementInternals (Verhaltensänderung, eventuell Breaking).\n- BEM-Bereinigung mit CLI-Tasks `ScssRename*` und Migrationsguide für Custom-Themes.\n\n## Offene Fragen für die Detailpläne\n\n1. ~~Sind die Shell-Adapter (alte FC → neue FC) als Zwischenschicht akzeptabel? (G1.3)~~ Entschieden: ja, siehe G1.3.\n2. ~~ID-Strategie: bisherige Erzeugung für Snapshot-Parität oder DD12 `createUniqueId`? (G1.4)~~ Kein Konflikt: Legacy nutzt bereits `createUniqueId` und `createRelatedUniqueId`. Die Basis-ID wird einmal pro Instanz als `@State()` erzeugt.\n3. ~~`_touched` als `@State` oder als Render-Prop? (G1.4)~~ Entschieden: Render-Prop. `_touched` bleibt `@Prop({ mutable: true, reflect: true })`, der Blur-Handler schreibt die Prop (Vorbild `_open` in `kol-details`).\n4. ~~`_on`: eine gemeinsame Callback-Prop oder typisiert pro Feld? (G1.1)~~ Entschieden: gemeinsam, alle Felder deklarieren `InputTypeOnDefault`.\n5. ~~SSR-Absturz von `attachInternals(undefined)` 1:1 übernehmen oder mit eigenem PR über einen Guard absichern? (G1.2)~~ Entschieden: 1:1 übernehmen, Fix als eigener PR nach G1.2 (#11034). Ursache ist nicht ein leeres `@Element()`: In mock-doc greift `instanceof Element` in `findHostWithShadowRoot` nicht. Betroffen sind im SSR die inneren `kol-button-wc`/`kol-popover-button-wc` und mit `serializeShadowRoot: 'scoped'` alle Legacy-Felder.\n6. ~~Verhaltensverträge in Jest oder in Playwright? (G0)~~ Entschieden: Playwright, siehe G0.\n7. ~~Namen der Input-Props für min/max/step. (G3)~~ Entschieden: `inputMinProp`, `inputMaxProp` und `stepProp`, analog zu `horizontalIconsProp` (G1.1).\n8. ~~`kol-select-wc` als Übergangs-Tag behalten oder `pagination` direkt auf das FC umstellen? (G5)~~ Entschieden: `kol-select` rendert das FC direkt. `kol-select-wc` bleibt als Übergangs-Tag für `pagination`, mit derselben Basis; die Ablösung braucht Theme-Änderungen (G7). Umgesetzt in G7.6 und G7.7.\n9. ~~combobox und single-select: gemeinsame DD16-Basis oder `ListboxBehavior`? (G5)~~ Entschieden: gemeinsame Basis `BaseListboxWebComponent extends BaseFormFieldWebComponent`, wie `BaseTextInputWebComponent` in G2.\n10. ~~#10501 und #10617 vor oder nach der Migration fixen? (G5)~~ Entschieden: nach der Migration, als eigener PR auf dem migrierten Code. Die Migration übernimmt das Verhalten 1:1.\n\n## Grundlagen\n\n- `packages/components/src/components/_skeleton/ARC42.md`\n- Skill `.claude/skills/migrate-to-skeleton/` (inkl. `reference/patterns.md`, `reference/pitfalls.md`)\n- Skill `.claude/skills/zero-visual-delta-handoff/`\n",
418
418
  "kind": "doc"
419
419
  },
420
420
  {
@@ -521,7 +521,7 @@
521
521
  "name": "README",
522
522
  "description": "KoliBri is not a design system in the traditional sense. Rather, we extend the HTML5 standard with self-contained, accessible Web Components — new HTML elements that work independently from any design or branding. These atomic components form a foundation that any design library, framework, or…",
523
523
  "path": "README.md",
524
- "code": "# Welcome to KoliBri\n\n[![npm](https://img.shields.io/npm/v/@public-ui/components)](https://www.npmjs.com/package/@public-ui/components)\n[![license](https://img.shields.io/npm/l/@public-ui/components)](https://github.com/public-ui/kolibri/blob/develop/LICENSE)\n[![downloads](https://img.shields.io/npm/dt/@public-ui/components)](https://www.npmjs.com/package/@public-ui/components)\n[![issues](https://img.shields.io/github/issues/public-ui/kolibri)](https://github.com/public-ui/kolibri/issues)\n[![pull requests](https://img.shields.io/github/issues-pr/public-ui/kolibri)](https://github.com/public-ui/kolibri/pulls)\n[![size](https://img.shields.io/bundlephobia/min/@public-ui/components)](https://bundlephobia.com/result?p=@public-ui/components)\n![contributors](https://img.shields.io/github/contributors/public-ui/kolibri)\n[![mcp-oplist](https://mcptoplist.com/badge/glama%2Fpublic-ui%2Fkolibri.svg)](https://mcptoplist.com/server/glama%2Fpublic-ui%2Fkolibri)\n\n> \"The accessible HTML standard\"\n\nKoliBri is **not a design system** in the traditional sense. Rather, we extend the HTML5 standard with self-contained, accessible Web Components — new HTML elements that work independently from any design or branding. These atomic components form a foundation that any design library, framework, or style guide can reuse and theme according to their needs.\n\n**KoliBri** stands for \"component library for accessibility\" and was released as\nopen source by the\n[Informationstechnikzentrum Bund (ITZBund)](https://itzbund.de) for reuse and\ncontinued development.\n\n## Vision\n\nTogether we make **HTML** accessible using **reusable web components** to ensure **usability** and **accessibility**.\n\n## Mission\n\nThe [HTML web standard](https://html.spec.whatwg.org) is itself very “openly” specified in order to be as long-lasting and robust as possible. It therefore often happens that HTML compositions are not easily accessible, semantic and valid.\n\nKoliBri is based directly on the [Web standards](https://www.w3.org/standards/webdesign/) of the [W3C](https://www.w3.org) (framework-agnostic), and is generic Reference implementation of the [WCAG standard](https://www.w3.org/WAI/standards-guidelines/wcag/) and the [BITV](https://www.bitvtest.de/bitv_test.html) for accessibility and implemented as a multi-theming capable presentation layer. There is no technical reference and no data transfer functionality. This means that KoliBri is equally reusable for the realization of static websites as well as dynamic web applications with different corporate designs and style guides and is therefore very interesting for open source.\n\n## Roadmap\n\nKoliBri is always actively working on improvements, new features and future-oriented innovations for the latest major release. In parallel, a selected LTS release is maintained with regard to bug fixes.\n\n| Version | Release type | Release | Period | End-of-Support |\n| ------: | :----------: | :------: | :----: | :------------: |\n| 0.x | Initial | Jul 2020 | - | Dec 2021 |\n| 1.x | LTS | Dec 2021 | 3y | Dec 2024 |\n| 2.x | LTS | Dec 2023 | 3y | Dec 2026 |\n| 3.x | STS | Dec 2024 | 15m | Mar 2026 |\n| 4.x | LTS | Dec 2025 | 3y | Dec 2028 |\n| 5.x | STS | Dec 2026 | 15m | Mar 2028 |\n\n```mermaid\ngantt\n title LTS & STS\n dateFormat YYYY-MM-DD\n\n 0.x Initial implementation :, 2020-07-01, 17M\n 1.x (LTS) :, 2021-12-01, 3y\n 2.x (LTS) :, 2023-12-01, 3y\n 3.x (STS) :crit , 2024-12-01, 15M\n 4.x (LTS) :, 2025-12-01, 3y\n 5.x (STS) :crit , 2026-12-01, 15M\n 6.x (LTS) :, 2027-12-01, 3y\n\n```\n\n## Installation\n\nInstall the packages with [pnpm](https://pnpm.io):\n\n```bash\npnpm install\n```\n\nRun the build once to generate the components:\n\n```bash\npnpm -r build\n```\n\nFor working on the monorepo itself, see the [daily workflow](CONTRIBUTING.md#daily-workflow).\n\n### Quick start\n\nInstall the default theme and register the components:\n\n```ts\npnpm add @public-ui/components @public-ui/theme-default\n\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nregister(DEFAULT, defineCustomElements);\n```\n\n### Avoid CSS Custom Property Collisions\n\nKoliBri themes expose a few CSS custom properties so consumers can adapt the look and feel.\nBecause these properties remain global—even inside a Shadow DOM—using too many of them can\nclash with variables defined on the host page.\n\nUse namespaced custom properties only for values that must be overridden from the outside.\nFor internal calculations rely on SASS variables instead of additional CSS properties.\nThis keeps components robust and prevents unexpected style leaks.\n\n## Collaboration and cooperation\n\nThe **focus** of KoliBri is on **small** (atomic), very **flexible** and highly **reusable** HTML compositions (e.g. buttons). We offer an accessible, semantic and valid standard implementation of such components that can be reused for any higher-level HTML structure or component (molecule, organism or template).\nThese atomic components are where we should **collaborate** and **cooperate** to combine our skills and knowledge. The synergy effects on the basic components allow you to focus more on subject-specific content.\n\nLet's make KoliBri **better** and **more colorful** together!\n\n> Continue [to **Documentation**](https://public-ui.github.io/en/)…\n\n## Contributing\n\nBug reports and pull requests are welcome. Please read our [contribution guide](./CONTRIBUTING.md) before getting started.\n\n## SLSA/Provenance\n\nWe aim for **SLSA Build Level 3** for the npm packages published from this repository. Releases are built in GitHub Actions with OIDC-based identity and published with npm provenance (`--provenance`), producing verifiable attestations for the published artifacts. See the [publish workflow](./.github/workflows/publish.yml) for the release steps and npm provenance configuration.\n\n**Verification example**\n\n```bash\n# Inspect provenance metadata for a published package\npnpm view @public-ui/components dist.provenance\n\n# (Optional) Verify signatures/provenance if your npm client supports it\npnpm audit signatures --package=@public-ui/components@<version>\n```\n\n## Resources\n\n- [Get Started](https://public-ui.github.io/en/docs/get-started/first-steps)\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Known Issues](http://public-ui.github.io/en/docs/known-issues)\n- [Security](./docs/SECURITY.md)\n",
524
+ "code": "# Welcome to KoliBri\n\n[![a11y](https://img.shields.io/badge/a11y-WCAG_2.2_%2B_BITV_2.0-1B7F4D)](#mission)\n[![last commit](https://img.shields.io/github/last-commit/public-ui/kolibri/develop)](https://github.com/public-ui/kolibri/commits/develop)\n\n[![MCP server](https://img.shields.io/npm/v/@public-ui/mcp?label=MCP%20server)](https://public-ui-kolibri-mcp.vercel.app/)\n[![Agent skills](https://img.shields.io/badge/Agent_Skills-repo-58427C)](https://github.com/public-ui/agent-skills)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](./CONTRIBUTING.md)\n\n[![weekly downloads](https://img.shields.io/npm/dw/@public-ui/components)](https://www.npmjs.com/package/@public-ui/components)\n[![dependents](https://img.shields.io/librariesio/dependents/npm/@public-ui/components)](https://libraries.io/npm/@public-ui/components)\n[![stars](https://img.shields.io/github/stars/public-ui/kolibri)](https://github.com/public-ui/kolibri/stargazers)\n[![contributors](https://img.shields.io/github/contributors/public-ui/kolibri)](https://github.com/public-ui/kolibri/graphs/contributors)\n\n[![license](https://img.shields.io/npm/l/@public-ui/components)](https://github.com/public-ui/kolibri/blob/develop/LICENSE)\n[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](#slsaprovenance)\n\n> \"The accessible HTML standard\"\n\nKoliBri is **not a design system** in the traditional sense. Rather, we extend the HTML5 standard with self-contained, accessible Web Components — new HTML elements that work independently from any design or branding. These atomic components form a foundation that any design library, framework, or style guide can reuse and theme according to their needs.\n\n**KoliBri** stands for \"component library for accessibility\" and was released as\nopen source by the\n[Informationstechnikzentrum Bund (ITZBund)](https://itzbund.de) for reuse and\ncontinued development.\n\n## Vision\n\nTogether we make **HTML** accessible using **reusable web components** to ensure **usability** and **accessibility**.\n\n## Mission\n\nThe [HTML web standard](https://html.spec.whatwg.org) is itself very “openly” specified in order to be as long-lasting and robust as possible. It therefore often happens that HTML compositions are not easily accessible, semantic and valid.\n\nKoliBri is based directly on the [Web standards](https://www.w3.org/standards/webdesign/) of the [W3C](https://www.w3.org) (framework-agnostic), and is generic Reference implementation of the [WCAG standard](https://www.w3.org/WAI/standards-guidelines/wcag/) and the [BITV](https://www.bitvtest.de/bitv_test.html) for accessibility and implemented as a multi-theming capable presentation layer. There is no technical reference and no data transfer functionality. This means that KoliBri is equally reusable for the realization of static websites as well as dynamic web applications with different corporate designs and style guides and is therefore very interesting for open source.\n\n## Roadmap\n\nKoliBri is always actively working on improvements, new features and future-oriented innovations for the latest major release. In parallel, a selected LTS release is maintained with regard to bug fixes.\n\n| Version | Release type | Release | Period | End-of-Support |\n| ------: | :----------: | :------: | :----: | :------------: |\n| 0.x | Initial | Jul 2020 | - | Dec 2021 |\n| 1.x | LTS | Dec 2021 | 3y | Dec 2024 |\n| 2.x | LTS | Dec 2023 | 3y | Dec 2026 |\n| 3.x | STS | Dec 2024 | 15m | Mar 2026 |\n| 4.x | LTS | Dec 2025 | 3y | Dec 2028 |\n| 5.x | STS | Dec 2026 | 15m | Mar 2028 |\n\n```mermaid\ngantt\n title LTS & STS\n dateFormat YYYY-MM-DD\n\n 0.x Initial implementation :, 2020-07-01, 17M\n 1.x (LTS) :, 2021-12-01, 3y\n 2.x (LTS) :, 2023-12-01, 3y\n 3.x (STS) :crit , 2024-12-01, 15M\n 4.x (LTS) :, 2025-12-01, 3y\n 5.x (STS) :crit , 2026-12-01, 15M\n 6.x (LTS) :, 2027-12-01, 3y\n\n```\n\n## Installation\n\nInstall the packages with [pnpm](https://pnpm.io):\n\n```bash\npnpm install\n```\n\nRun the build once to generate the components:\n\n```bash\npnpm -r build\n```\n\nFor working on the monorepo itself, see the [daily workflow](CONTRIBUTING.md#daily-workflow).\n\n### Quick start\n\nInstall the default theme and register the components:\n\n```ts\npnpm add @public-ui/components @public-ui/theme-default\n\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\n\nregister(DEFAULT, defineCustomElements);\n```\n\n### Avoid CSS Custom Property Collisions\n\nKoliBri themes expose a few CSS custom properties so consumers can adapt the look and feel.\nBecause these properties remain global—even inside a Shadow DOM—using too many of them can\nclash with variables defined on the host page.\n\nUse namespaced custom properties only for values that must be overridden from the outside.\nFor internal calculations rely on SASS variables instead of additional CSS properties.\nThis keeps components robust and prevents unexpected style leaks.\n\n## Collaboration and cooperation\n\nThe **focus** of KoliBri is on **small** (atomic), very **flexible** and highly **reusable** HTML compositions (e.g. buttons). We offer an accessible, semantic and valid standard implementation of such components that can be reused for any higher-level HTML structure or component (molecule, organism or template).\nThese atomic components are where we should **collaborate** and **cooperate** to combine our skills and knowledge. The synergy effects on the basic components allow you to focus more on subject-specific content.\n\nLet's make KoliBri **better** and **more colorful** together!\n\n> Continue [to **Documentation**](https://public-ui.github.io/en/)…\n\n## Contributing\n\nBug reports and pull requests are welcome. Please read our [contribution guide](./CONTRIBUTING.md) before getting started.\n\n## SLSA/Provenance\n\nWe aim for **SLSA Build Level 3** for the npm packages published from this repository. Releases are built in GitHub Actions with OIDC-based identity and published with npm provenance (`--provenance`), producing verifiable attestations for the published artifacts. See the [publish workflow](./.github/workflows/publish.yml) for the release steps and npm provenance configuration.\n\n**Verification example**\n\n```bash\n# Inspect provenance metadata for a published package\npnpm view @public-ui/components dist.provenance\n\n# (Optional) Verify signatures/provenance if your npm client supports it\npnpm audit signatures --package=@public-ui/components@<version>\n```\n\n## Resources\n\n- [Get Started](https://public-ui.github.io/en/docs/get-started/first-steps)\n- [Contributing](./CONTRIBUTING.md)\n- [Code of Conduct](./CODE_OF_CONDUCT.md)\n- [Known Issues](http://public-ui.github.io/en/docs/known-issues)\n- [Security](./docs/SECURITY.md)\n",
525
525
  "kind": "doc"
526
526
  },
527
527
  {
@@ -2370,6 +2370,19 @@
2370
2370
  "code": "import React, { useState } from 'react';\n\nimport { KolProgress } from '@public-ui/react-v19';\n\nimport type { FC } from 'react';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const ProgressChanging: FC = () => {\n\tconst [val, setVal] = useState<number>(5);\n\tconst [max, setMax] = useState<number>(10);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This shows that values can be changed and that they are clamped at max value (here at 10).</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<fieldset title=\"changing\" className=\"flex flex-col gap-4\">\n\t\t\t\t<div className=\"flex gap-4\">\n\t\t\t\t\t<button onClick={() => setVal(-2)}>set -2</button>\n\t\t\t\t\t<button onClick={() => setVal(5)}>set 5</button>\n\t\t\t\t\t<button onClick={() => setVal(13)}>set 13</button>\n\n\t\t\t\t\t<button onClick={() => setMax(-1)}>change max to -1</button>\n\t\t\t\t\t<button onClick={() => setMax(5)}>change max to 5</button>\n\t\t\t\t\t<button onClick={() => setMax(10)}>change max to 10</button>\n\t\t\t\t</div>\n\n\t\t\t\t<KolProgress _label={`Showing ${val} of ${max}`} _variant=\"bar\" _max={max} _value={val}></KolProgress>\n\t\t\t\t<KolProgress _variant=\"cycle\" _max={max} _value={val}></KolProgress>\n\t\t\t</fieldset>\n\t\t</>\n\t);\n};\n",
2371
2371
  "kind": "sample"
2372
2372
  },
2373
+ {
2374
+ "id": "sample/progress/dynamic",
2375
+ "group": "progress",
2376
+ "name": "dynamic",
2377
+ "description": "The value grows by every second and starts again at 0 after. Screen readers announce the current value every 5 seconds through the live region. Removing and inserting the components again checks that the announcement continues afterwards.",
2378
+ "tags": [
2379
+ "kol-button",
2380
+ "kol-progress"
2381
+ ],
2382
+ "path": "packages/samples/react/src/components/progress/dynamic.tsx",
2383
+ "code": "import React, { useEffect, useState } from 'react';\n\nimport { KolButton, KolProgress } from '@public-ui/react-v19';\n\nimport type { FC } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst MAX = 100;\nconst STEP = 5;\nconst TICK_MS = 1000;\n\nexport const ProgressDynamic: FC = () => {\n\tconst [value, setValue] = useState<number>(0);\n\tconst [running, setRunning] = useState<boolean>(true);\n\tconst [mounted, setMounted] = useState<boolean>(true);\n\n\tuseEffect(() => {\n\t\tif (!running) {\n\t\t\treturn;\n\t\t}\n\t\tconst timer = setInterval(() => setValue((current) => (current >= MAX ? 0 : current + STEP)), TICK_MS);\n\t\treturn () => clearInterval(timer);\n\t}, [running]);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThe value grows by {STEP} every second and starts again at 0 after {MAX}. Screen readers announce the current value every 5 seconds through the live\n\t\t\t\t\tregion. Removing and inserting the components again checks that the announcement continues afterwards.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"progress-dynamic\" skipSnapshot>\n\t\t\t\t<div className=\"flex gap-4\">\n\t\t\t\t\t<KolButton _label={running ? 'Pause' : 'Resume'} _on={{ onClick: () => setRunning(!running) }} />\n\t\t\t\t\t<KolButton _label={mounted ? 'Remove' : 'Insert'} _on={{ onClick: () => setMounted(!mounted) }} />\n\t\t\t\t</div>\n\n\t\t\t\t{mounted && (\n\t\t\t\t\t<>\n\t\t\t\t\t\t<KolProgress _label=\"Upload\" _variant=\"bar\" _max={MAX} _value={value} />\n\t\t\t\t\t\t<KolProgress _label=\"Upload\" _variant=\"cycle\" _max={MAX} _value={value} />\n\t\t\t\t\t</>\n\t\t\t\t)}\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
2384
+ "kind": "sample"
2385
+ },
2373
2386
  {
2374
2387
  "id": "sample/quote/basic",
2375
2388
  "group": "quote",
@@ -3010,7 +3023,7 @@
3010
3023
  "kol-tabs"
3011
3024
  ],
3012
3025
  "path": "packages/samples/react/src/components/tabs/align.tsx",
3013
- "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolHeading, KolTabs } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nexport const TabsAlign: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows KolTabs with the property <code>_align</code> set to <code>left</code>, <code>right</code>, <code>top</code> and <code>bottom</code>.\n\t\t\t</p>\n\t\t</SampleDescription>\n\t\t<div className=\"grid gap-8\">\n\t\t\t{(['left', 'right', 'top', 'bottom'] as AlignPropType[]).map((align) => {\n\t\t\t\tconst text = `Tabs with ${align} align`;\n\t\t\t\treturn (\n\t\t\t\t\t<div key={align} className=\"grid gap-4\">\n\t\t\t\t\t\t<KolHeading _level={2} _label={text} />\n\t\t\t\t\t\t<KolTabs _tabs={tabs} _align={align} _label={text}>\n\t\t\t\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t\t\t\t</KolTabs>\n\t\t\t\t\t</div>\n\t\t\t\t);\n\t\t\t})}\n\t\t</div>\n\t</>\n);\n",
3026
+ "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolHeading, KolTabs } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nexport const TabsAlign: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows KolTabs with the property <code>_align</code> set to <code>left</code>, <code>right</code>, <code>top</code> and <code>bottom</code>.\n\t\t\t</p>\n\t\t</SampleDescription>\n\t\t<div className=\"grid gap-8\">\n\t\t\t{(['left', 'right', 'top', 'bottom'] as AlignPropType[]).map((align) => {\n\t\t\t\tconst text = `Tabs with ${align} align`;\n\t\t\t\treturn (\n\t\t\t\t\t<div key={align} className=\"grid gap-4\">\n\t\t\t\t\t\t<KolHeading _level={2} _label={text} />\n\t\t\t\t\t\t<KolTabs _tabs={tabs} _align={align} _label={text}>\n\t\t\t\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t\t\t\t</KolTabs>\n\t\t\t\t\t</div>\n\t\t\t\t);\n\t\t\t})}\n\t\t</div>\n\t</>\n);\n",
3014
3027
  "kind": "sample"
3015
3028
  },
3016
3029
  {
@@ -3022,7 +3035,7 @@
3022
3035
  "kol-tabs"
3023
3036
  ],
3024
3037
  "path": "packages/samples/react/src/components/tabs/basic.tsx",
3025
- "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolTabs } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nconst tabsWithoutIcons = tabs.map((tab) => ({\n\t...tab,\n\t_icons: undefined,\n}));\n\nexport const TabsBasic: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>KolTabs renders tab captions and their associated content. This sample shows tab captions with and without icons and disabled tabs.</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"regular\">\n\t\t\t<KolTabs _tabs={tabsWithoutIcons} _label=\"Regular tabs\">\n\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\n\t\t<SampleBlock id=\"icons\">\n\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _label=\"Tabs with icons\">\n\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\t</>\n);\n",
3038
+ "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolTabs } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nconst tabsWithoutIcons = tabs.map((tab) => ({\n\t...tab,\n\t_icons: undefined,\n}));\n\nexport const TabsBasic: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>KolTabs renders tab captions and their associated content. This sample shows tab captions with and without icons and disabled tabs.</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"regular\">\n\t\t\t<KolTabs _tabs={tabsWithoutIcons} _label=\"Regular tabs\">\n\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\n\t\t<SampleBlock id=\"icons\">\n\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _label=\"Tabs with icons\">\n\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\t</>\n);\n",
3026
3039
  "kind": "sample"
3027
3040
  },
3028
3041
  {
@@ -3035,7 +3048,7 @@
3035
3048
  "kol-tabs"
3036
3049
  ],
3037
3050
  "path": "packages/samples/react/src/components/tabs/behavior.tsx",
3038
- "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolHeading, KolTabs } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nexport const TabsBehavior: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows KolTabs with the property <code>_behavior</code> set to <code>select-manual</code> and <code>select-automatic</code>.\n\t\t\t</p>\n\t\t\t<p>This property allows controlling when an arrow key is pressed whether the tab change takes place right away or only focuses the tab caption.</p>\n\t\t</SampleDescription>\n\t\t<div className=\"grid gap-8\">\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<KolHeading _level={2} _label='Tabs with \"select manual\" behavior' />\n\t\t\t\t<KolTabs _tabs={tabs} _behavior=\"select-manual\" _label=\"Tabs with select manual behavior\">\n\t\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t\t</KolTabs>\n\t\t\t</div>\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<KolHeading _level={2} _label='Tabs with \"select automatic\" behavior' />\n\t\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _behavior=\"select-automatic\" _label=\"Tabs with select automatic behavior\">\n\t\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t\t</KolTabs>\n\t\t\t</div>\n\t\t</div>\n\t</>\n);\n",
3051
+ "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolHeading, KolTabs } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\n\nexport const TabsBehavior: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows KolTabs with the property <code>_behavior</code> set to <code>select-manual</code> and <code>select-automatic</code>.\n\t\t\t</p>\n\t\t\t<p>This property allows controlling when an arrow key is pressed whether the tab change takes place right away or only focuses the tab caption.</p>\n\t\t</SampleDescription>\n\t\t<div className=\"grid gap-8\">\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<KolHeading _level={2} _label='Tabs with \"select manual\" behavior' />\n\t\t\t\t<KolTabs _tabs={tabs} _behavior=\"select-manual\" _label=\"Tabs with select manual behavior\">\n\t\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t\t</KolTabs>\n\t\t\t</div>\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<KolHeading _level={2} _label='Tabs with \"select automatic\" behavior' />\n\t\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _behavior=\"select-automatic\" _label=\"Tabs with select automatic behavior\">\n\t\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t\t</KolTabs>\n\t\t\t</div>\n\t\t</div>\n\t</>\n);\n",
3039
3052
  "kind": "sample"
3040
3053
  },
3041
3054
  {
@@ -3047,7 +3060,7 @@
3047
3060
  "kol-tabs"
3048
3061
  ],
3049
3062
  "path": "packages/samples/react/src/components/tabs/create-button.tsx",
3050
- "code": "import { KolTabs } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const CreateButton: FC = () => {\n\tconst [tabs, setTabs] = useState([\n\t\t{\n\t\t\t_label: 'First tab',\n\t\t},\n\t\t{\n\t\t\t_label: 'Second Tab',\n\t\t},\n\t]);\n\n\tconst addTab = () => {\n\t\tsetTabs([\n\t\t\t...tabs,\n\t\t\t{\n\t\t\t\t_label: `Tab #${tabs.length + 1}`,\n\t\t\t},\n\t\t]);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This sample shows KolTabs with a &quot;create tab&quot; button.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"create-button\">\n\t\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _label=\"Tabs with create button\" _hasCreateButton _on={{ onCreate: addTab }}>\n\t\t\t\t\t{tabs.map((tab, index) => (\n\t\t\t\t\t\t<div key={`tab-${index}`} slot={`tab-${index}`}>\n\t\t\t\t\t\t\tContents of {tab._label}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t))}\n\n\t\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t</KolTabs>\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
3063
+ "code": "import { KolTabs } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const CreateButton: FC = () => {\n\tconst [tabs, setTabs] = useState([\n\t\t{\n\t\t\t_label: 'First tab',\n\t\t},\n\t\t{\n\t\t\t_label: 'Second Tab',\n\t\t},\n\t]);\n\n\tconst addTab = () => {\n\t\tsetTabs([\n\t\t\t...tabs,\n\t\t\t{\n\t\t\t\t_label: `Tab #${tabs.length + 1}`,\n\t\t\t},\n\t\t]);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This sample shows KolTabs with a &quot;create tab&quot; button.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"create-button\">\n\t\t\t\t<KolTabs _tabs={tabs} className=\"mt-4\" _label=\"Tabs with create button\" _hasCreateButton _on={{ onCreate: addTab }}>\n\t\t\t\t\t{tabs.map((tab, index) => (\n\t\t\t\t\t\t<p key={`tab-${index}`} slot={`tab-${index}`}>\n\t\t\t\t\t\t\tContents of {tab._label}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t))}\n\n\t\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t</KolTabs>\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
3051
3064
  "kind": "sample"
3052
3065
  },
3053
3066
  {
@@ -3059,7 +3072,7 @@
3059
3072
  "kol-tabs"
3060
3073
  ],
3061
3074
  "path": "packages/samples/react/src/components/tabs/icons-only.tsx",
3062
- "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolTabs } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\nexport const TabsIconsOnly: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>This sample shows KolTabs with hidden labels.</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"icons-only\">\n\t\t\t<KolTabs _label=\"Tabs with icons\" _tabs={tabs}>\n\t\t\t\t<div slot=\"tab-0\">Contents of Tab 1</div>\n\t\t\t\t<div slot=\"tab-1\">Contents of Tab 2</div>\n\t\t\t\t<div slot=\"tab-2\">Contents of Tab 3</div>\n\t\t\t\t<div slot=\"tab-3\">Contents of Tab 4</div>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\t</>\n);\n",
3075
+ "code": "import type { FC } from 'react';\nimport React from 'react';\n\nimport { KolTabs } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst tabs = [\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-check',\n\t\t_label: 'First tab',\n\t\t_on: {\n\t\t\tonSelect: (event: Event) => {\n\t\t\t\tconsole.log('First tab selected', event);\n\t\t\t},\n\t\t},\n\t},\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-link-external',\n\t\t_label: 'Second Tab',\n\t},\n\t{\n\t\t_disabled: true,\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-house',\n\t\t_label: 'Disabled Tab',\n\t},\n\t{\n\t\t_hideLabel: true,\n\t\t_icons: 'kolicon-eye',\n\t\t_label: 'Last tab',\n\t},\n];\nexport const TabsIconsOnly: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>This sample shows KolTabs with hidden labels.</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"icons-only\">\n\t\t\t<KolTabs _label=\"Tabs with icons\" _tabs={tabs}>\n\t\t\t\t<p slot=\"tab-0\">Contents of Tab 1</p>\n\t\t\t\t<p slot=\"tab-1\">Contents of Tab 2</p>\n\t\t\t\t<p slot=\"tab-2\">Contents of Tab 3</p>\n\t\t\t\t<p slot=\"tab-3\">Contents of Tab 4</p>\n\t\t\t</KolTabs>\n\t\t</SampleBlock>\n\t</>\n);\n",
3063
3076
  "kind": "sample"
3064
3077
  },
3065
3078
  {
@@ -3636,7 +3649,7 @@
3636
3649
  "name": "ARC42-SKELETON",
3637
3650
  "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.",
3638
3651
  "path": "packages/tools/mcp/node_modules/@public-ui/components/docs/ARC42-SKELETON.md",
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",
3652
+ "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#### Shared Shell Root of the Form Fields\n\nThe 14 form fields (`kol-combobox`, the `kol-input-*` fields, `kol-select`, `kol-single-select`, `kol-textarea`) share one shell. `FormFieldFC` renders the root `BemRootNodeFC block=\"kol-form-field\"`, and its sub-FCs carry registered blocks of their own (`kol-input-container`, `kol-field-control`, `kol-input`, `kol-textarea`, …). The block of the field is an additional class on that shared root:\n\n```html\n<div class=\"kol-form-field kol-input-email email …\">\n\t<div class=\"kol-input-container …\">\n\t\t<input class=\"kol-input …\" type=\"email\" />\n\t</div>\n</div>\n```\n\n- A component may use the root of a shared shell as its own root when several components render that shell. The shell blocks and their elements are the theming contract every theme styles across all fields; the component block on the root scopes rules to one field.\n- `render()` renders exactly one root FC: for a form field that is `FormFieldFC`, composed with the shell FCs as its children. A per-field FC around this composition is not required.\n- The component block is registered in `bem-registry.ts` like any other block (see _Registration requirement_). The classes without BEM form on the root (`email`, `password`, `has-value`, …) are part of the theming contract; replacing them is a theming breaking change (design decision 17).\n\n#### Embedded Roots Keep Their Element Wrapper\n\nWhere a component places an embedded FC with a block of its own, the position is an element of the embedding block that wraps the embedded root, even without siblings: `div.kol-button__tooltip > div.kol-tooltip`, `div.kol-breadcrumb__link > div.kol-link`, `span.kol-tree-item__toggle-button > i.kol-icon`. A BEM mix on one node (`div.kol-tooltip.kol-button__tooltip`) is not used, because the rules of two blocks would compete on that node. Such an element wrapper is no flat-DOM finding; a wrapper around an element of the component's own block is.\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.\n19. **Form fields share the `kol-form-field` root**\n - _Pattern_: the form fields render the shared shell root `kol-form-field` and carry their own block as an additional class; see [Shared Shell Root of the Form Fields](#shared-shell-root-of-the-form-fields).\n - _Alternative_: give every field a root with its own block and elements (`kol-input-email__label`, `__input`, `__msg`).\n - _Reason_: the shell is one structure for 14 fields, and every theme styles it once through the shell blocks. Own roots per field would break the theming of all 14 fields in all themes for uniform BEM naming alone, without any change for users.\n20. **Element wrappers around embedded roots instead of BEM mixes**\n - _Pattern_: an embedded FC root sits inside an element of the embedding block; see [Embedded Roots Keep Their Element Wrapper](#embedded-roots-keep-their-element-wrapper).\n - _Alternative_: a BEM mix that puts the embedding element class on the embedded root and saves one node.\n - _Reason_: the wrapper keeps the rules of both blocks on separate nodes; a mix would make them compete and change the theming contract of every affected component.\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",
3640
3653
  "kind": "spec"
3641
3654
  },
3642
3655
  {
@@ -4000,7 +4013,7 @@
4000
4013
  "name": "table-stateful",
4001
4014
  "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.",
4002
4015
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateful.md",
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",
4016
+ "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. The component resolves the IDs and sets them as element references (`ariaLabelledByElements`) on the native `<table>` inside the shadow root, because IDREF attributes cannot cross that boundary. Desktop screen readers (NVDA, JAWS with Chrome/Firefox) follow the references; VoiceOver and TalkBack do not — 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",
4004
4017
  "kind": "spec"
4005
4018
  },
4006
4019
  {
@@ -4008,7 +4021,7 @@
4008
4021
  "group": "spec",
4009
4022
  "name": "table-stateless",
4010
4023
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateless.md",
4011
- "code": "# kol-table-stateless\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\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| `_headerCells` | `_header-cells` | <span class=\"text-red-500\">**[DEPRECATED]**</span> Will be removed in the future. Use _headers instead. Defines the horizontal and vertical table headers.<br/><br/> | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }` | `undefined` |\n| `_headers` | `_headers` | Defines the horizontal and vertical table headers. | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| 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 \\| { onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; }` | `undefined` |\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----------------------------------------------\n\n\n",
4024
+ "code": "# kol-table-stateless\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_ariaLabelledby` | `_aria-labelledby` | References an external element by ID that serves as the accessible label for this table. The component resolves the IDs and sets them as element references (`ariaLabelledByElements`) on the native `<table>` inside the shadow root, because IDREF attributes cannot cross that boundary. Desktop screen readers (NVDA, JAWS with Chrome/Firefox) follow the references; VoiceOver and TalkBack do not — 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| `_headerCells` | `_header-cells` | <span class=\"text-red-500\">**[DEPRECATED]**</span> Will be removed in the future. Use _headers instead. Defines the horizontal and vertical table headers.<br/><br/> | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }` | `undefined` |\n| `_headers` | `_headers` | Defines the horizontal and vertical table headers. | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| 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 \\| { onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; }` | `undefined` |\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----------------------------------------------\n\n\n",
4012
4025
  "kind": "spec"
4013
4026
  },
4014
4027
  {