@public-ui/mcp 5.0.0-beta.0 → 5.0.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "metadata": {
3
- "generatedAt": "2026-10-26T08:17:55.178Z",
3
+ "generatedAt": "2026-11-12T15:26:48.919Z",
4
4
  "buildMode": "ci",
5
5
  "counts": {
6
- "total": 347,
7
- "totalDocs": 66,
6
+ "total": 350,
7
+ "totalDocs": 69,
8
8
  "totalSpecs": 53,
9
9
  "totalSamples": 208,
10
10
  "totalScenarios": 20
11
11
  },
12
12
  "repo": {
13
- "commit": "850cc697c08badd41b0ddca9c517ea2c869efe23",
13
+ "commit": "b219b377e2228de2510d554556620e074d3360ee",
14
14
  "branch": "develop",
15
15
  "repoUrl": "https://github.com/public-ui/kolibri"
16
16
  }
@@ -22,7 +22,7 @@
22
22
  "name": "AGENTS",
23
23
  "description": "This repository is a monorepo managed with pnpm and Nx. It contains multiple packages under packages/ such as web components, themes, adapters, samples and tooling.",
24
24
  "path": "AGENTS.md",
25
- "code": "# Agent Instructions\n\nThis repository is a monorepo managed with **pnpm** and **Nx**. It contains multiple packages under `packages/` such as web components, themes, adapters, samples and tooling.\n\n## Handling hints\n\nWe have a monorepo structure with multiple packages, each with its own `package.json`. The root `package.json` contains shared dependencies and scripts. Use `pnpm` commands to manage dependencies and run scripts across packages.\n\n- To install dependencies, use `pnpm i` at the root level. This will install all dependencies for all packages.\n- If you change a dependency in a package:\n - Use only exact version numbers in `package.json`. Other peers will not be able to use the package if you can use a range version.\n - You need to run `pnpm i` at the root level. This updates the lockfile and ensures all packages are using the correct versions.\n- Never add a `packageManager` field to any `package.json` file.\n- Avoid that branch name may contain hidden characters.\n- Development workflow: `git pull` → `pnpm i` → `pnpm -r build` → `pnpm dev` only in the packages being changed → work on the code. No `dev` or `preview` script builds dependencies. Never run a build while a watcher is active, the components build clears the watcher's output. See [CONTRIBUTING.md](CONTRIBUTING.md#daily-workflow).\n- If something does not work, check in the event of an error whether all dependent submodules have been built.\n- To build a single package faster, run commands with downstream dependents using `pnpm --filter ...<package>` (e.g., `pnpm --filter ...@public-ui/sample-react build`). A package's build never builds another package: `pnpm -r build` builds each package exactly once in topological order. Build a package together with its dependencies using `pnpm --filter <package>... build` (e.g. components, which needs the kolicons font from `@public-ui/icons`).\n\n## 🚨 Format-first rule\n\n> **Stop before you commit:** run the formatter so CI never rejects your patch for style drift.\n\n1. Run `pnpm format` from the repo root whenever you change code, docs or configs.\n2. If you only touched one package, you may instead run `pnpm --filter <package> format` for a quicker pass.\n3. Re-stage the affected files (`git add -u`) so the formatted result is what lands in the commit.\n\nNo package scripts in this repo need extra flags such as `-- --write`; the scripts already know when to write changes versus just check.\n\n## Semantic Versioning\n\nThis repository follows **Semantic Versioning** (SemVer) for all packages. Each package version is defined in its own `package.json` file. The versioning scheme is as follows:\n\n- **Major version**: Incremented for incompatible API changes.\n- **Minor version**: Incremented for adding functionality in a backwards-compatible manner.\n- **Patch version**: Incremented for backwards-compatible bug fixes.\n\nThe public API of a component is its props, methods, events, slots and exported types, including their behaviour. Its internal DOM structure and the BEM classes on it are a **theming contract** instead: changing them is a **theming breaking change**, not a hard breaking change. It ships in at least a minor release, carries the label `release:theming` (changelog section _Theming_), lists the old and new classes in the pull request and adapts all themes of this repository in the same change. Theme authors adapt their themes through their own visual snapshots and the zero-visual-delta workflow. See [Theming Contract](packages/components/src/components/_skeleton/ARC42.md#theming-contract-shadow-dom-structure-and-bem-classes).\n\nIf we deprecate a feature, we will mark it as deprecated in the code and documentation, but we will not remove it immediately. Instead, we will provide a migration guide (migration\\*.md) for users to transition to the new feature. Also we provide a migration tool in the `packages/tools/kolibri-cli` package to help with the migration process. You have to add a migration task from the previous version to the new version in the `packages/tools/kolibri-cli/src/migrations` folder. In the migration package, are a lot of migration tasks already implemented, so you can use them as a reference.\n\n## Project Structure\n\n- `packages/components` – Stencil based web components\n - `packages/components/src/component` – components\n - `packages/components/src/schema` – schema definitions for all components\n- `packages/samples` – sample applications demonstrating usage\n - `packages/samples/angular` – Angular sample app; do not edit\n - `packages/samples/react` – React sample app; all samples; write component samples here\n- `packages/adapters/*` – generated framework integration packages; do not edit\n- `packages/themes` – style themes and assets\n - `packages/themes/default` – primary maintained standard theme\n - All other themes are not actively maintained\n- `packages/tools/kolibri-cli` – helper CLI for migration\n- Documentation lives in `docs/`.\n- `kol-tooltip-wc` (`packages/components/src/components/tooltip/component.tsx`) is the only `-wc` web component (`shadow: false`). It stays deprecated and is kept only for DESYBRI: do not remove, migrate or replace it, and do not use it in new code. Every other component that embeds another one renders that component's functional component through an item (see the skeleton ARC42, _Embedded Components (Items)_).\n- Do always ignore and do not edit all `assets` folders in all packages, as these are generated by the build process and should not be edited manually. If you need to change something in the assets, you have to change it in the source code and rebuild the package.\n\n## Theming\n\nThe theming is realized with adopted style sheets on web components and will be adopted at the mounted hook of the components. All following styling rules are only relevant for the `components` and `themes` packages.\n\n### The 5 styling layers\n\n1. **A11y Preset layer**: This layer comes out of the `adopted-style-sheets` package and contains the basic styles for accessibility. It is applied to all components.\n2. **Basis Global layer**: This layer contains the basis global styles for all components and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer. It never contains a color scheme (dark/light).\n3. **Basis Component layer**: This layer contains the basis styles for one component and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer. It never contains a color scheme (dark/light).\n4. **Theme Global layer**: This layer contains the global styles for all components of a theme and comes out of a own theme package, like `@public-ui/theme-default`. Color schemes (dark/light) are defined here via theme tokens.\n5. **Theme Component layer**: This layer contains the component specific styles for one component of a theme and comes out of a own theme package, like `@public-ui/theme-default`.\n\n> **Base styling vs. theming — dark/light lives in the theme.** The base styling of the components package (layers 1–3) is responsible for layout and structure only. It knows no dark/light color scheme: no `prefers-color-scheme`, no `color-scheme`, no `light-dark()`, no scheme tokens. Black and white in the base layers are a contrast fallback, not a color design. Dark/light theming is anchored and implemented exclusively in the theme packages (layers 4–5). See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](docs/BASE_STYLING_VS_THEMING_CONCEPT.md).\n\n### Global accessibility styles\n\n```css\n/*\n * This file contains all rules for accessibility.\n */\n@layer kol-global {\n\t:host {\n\t\t/*\n\t\t * Minimum size of interactive elements.\n\t\t */\n\t\t--a11y-min-size: #{rem(44)};\n\t\t/*\n\t\t * No element should be used without a background and font color whose contrast ratio has\n\t\t * not been checked. By initially setting the background color to white and the font color\n\t\t * to black, the contrast ratio is ensured and explicit adjustment is forced.\n\t\t */\n\t\tbackground-color: white;\n\t\tcolor: black;\n\t}\n\n\t* {\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\thyphens: auto;\n\t\t/*\n\t\t * Verdana is an accessible font that can be used without requiring additional loading time.\n\t\t */\n\t\tfont-family: Verdana;\n\t\t/*\n\t\t * Letter spacing is required for all texts.\n\t\t */\n\t\tletter-spacing: inherit;\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\tword-break: break-word;\n\t\t/*\n\t\t * Word spacing is required for all texts.\n\t\t */\n\t\tword-spacing: inherit;\n\t}\n\n\t/*\n\t * All interactive elements should have a minimum size of rem(44).\n\t */\n\t/* input:not([type='checkbox'], [type='radio'], [type='range']), */\n\t/* option, */\n\t/* select, */\n\t/* textarea, */\n\t[role='button'],\n\tbutton:not([role='link']),\n\t.kol-input .input {\n\t\tmin-height: var(--a11y-min-size);\n\t\tmin-width: var(--a11y-min-size);\n\t}\n\n\t/*\n\t * Some interactive elements should not inherit the font-family and font-size.\n\t */\n\ta,\n\tbutton,\n\th1,\n\th2,\n\th3,\n\th4,\n\th5,\n\th6,\n\tinput,\n\toption,\n\tselect,\n\ttextarea {\n\t\t/*\n\t\t * All elements should inherit the font family from his parent element.\n\t\t */\n\t\tfont-family: inherit;\n\t\t/*\n\t\t * All elements should inherit the font size from his parent element.\n\t\t */\n\t\tfont-size: inherit;\n\t}\n}\n\n/**\n * Sometimes we need the semantic element for accessibility reasons,\n * but we don't want to show it.\n *\n * - https://www.a11yproject.com/posts/how-to-hide-content/\n */\n.visually-hidden {\n\tclip: rect(0 0 0 0);\n\tclip-path: inset(50%);\n\theight: 1px;\n\toverflow: hidden;\n\tposition: absolute;\n\twhite-space: nowrap;\n\twidth: 1px;\n}\n```\n\n### Styling rules\n\nThe basis global layer set the default font-size and box-sizing for all components.\n\n```css\n@layer kol-global {\n\t:host {\n\t\tfont-size: rem(16);\n\t\t/*\n\t\t * The max-width is needed to prevent the table from overflowing the\n\t\t * parent node, if the table is wider than the parent node.\n\t\t */\n\t\tmax-width: 100%;\n\t}\n\n\t* {\n\t\t/*\n\t\t * We prefer to box-sizing: border-box for all elements.\n\t\t */\n\t\tbox-sizing: border-box;\n\t}\n ...\n}\n```\n\n### Custom Theming rules\n\nThe custom theme layer is used to set the colors and other theme specific styles. The custom theme layer should not contain any layout styles, as these are already set in the basis global and component layers.\n\nDark/light color schemes are implemented in the theme layers only. Define all colors that differ between light and dark as tokens on `:host` in the theme global layer and switch the scheme there (`color-scheme` + `light-dark()`, `@media (prefers-color-scheme: dark)`, or an opt-in attribute). The theme component layer only references those tokens and never contains its own scheme media queries. Alternatively, a theme may ship a separate dark export that is registered as an additional theme and switched via the `kol-theme` attribute. The base styling of the components package must never be involved in this.\n\nFor example, generally the font-family is set in the theme global layer, on the `:host` element, so that all components inherit the font-family from the theme. The font-size is set in the basis global layer, so that all components inherit the font-size from the basis global layer. But it is possible to set a other base font-size in the theme global layer, if needed.\n\n```css\n@layer kol-theme-global {\n\t:host {\n\t\t--font-family: var(--kolibri-font-family, Verdana, Arial, Calibri, Helvetica, sans-serif);\n\t\t--font-size: var(--kolibri-font-size, #{rem(16)});\n ...\n\t}\n\n\t:host {\n\t\tfont-size: var(--font-size);\n\n\t\t* {\n\t\t\tfont-family: var(--font-family);\n\t\t}\n\t}\n ...\n}\n```\n\nIn the theme component layer, you can set what ever you need to realize your own custom style guidelines. For example, you can set the colors, borders, shadows, etc. for the component.\n\n```css\n@layer kol-theme-component {\n ...\n}\n```\n\n### Color schemes\n\nA theme carries one palette per color scheme in a single declaration, resolved by the CSS\n`light-dark()` function:\n\n```scss\n@layer kol-theme-global {\n\t:host {\n\t\t--color-text: var(--kolibri-color-text, light-dark(#202020, #{$dark-color-text}));\n\t}\n}\n```\n\nRules that hold for every theme:\n\n- **Never declare `color-scheme` in a theme**, and never write `@media (prefers-color-scheme: …)`.\n `color-scheme` is an inherited property and inheritance follows the flat tree, so it crosses the\n shadow boundary on its own: each component resolves `light-dark()` against whatever the consuming\n application has in effect where the component sits. A declaration on `:host` would replace that\n inherited value, and the page and the components in it could then disagree — which is exactly the\n bug this rule exists to prevent.\n- The application owns the scheme, in plain CSS: `:root { color-scheme: light dark }` to follow the\n operating system, `color-scheme: dark` on any element to force a subtree. Consequently an\n application that declares nothing stays light, whatever the operating system says. Dark mode is\n opt-in; `color-scheme.css` in a theme package ships that one line plus the page colors.\n- Sass does not evaluate variables inside `var()`. Interpolate them (`#{$dark-color-text}`).\n- An application stylesheet that uses `light-dark()` must not be downlevelled. A CSS minifier\n targeting older browsers rewrites it into a `prefers-color-scheme` media query with space\n toggles, and that replacement ignores the `color-scheme` property. A theme's CSS is a string\n adopted into the shadow roots at runtime and is never processed by the application's CSS\n pipeline, so the page would follow the operating system while the components follow\n `color-scheme`. Both sample host apps therefore pin `build.cssTarget` in their Vite config.\n- The base layer hardcodes `black` and `white` in a few places. Where it routes them through a\n token, override the token (`--kol-a11y-font-color` / `--kol-a11y-background-color` in `a11y.scss`\n are the sanctioned hook for the host box of every component); elsewhere restate the declaration in\n a theme layer, which sits above `kol-a11y`, `kol-global` and `kol-component`. Keep the light\n branch byte identical to the base value so no light snapshot moves.\n- What a theme layer cannot reach are the color stops of a `@keyframes` rule declared in the base\n layer: an animation's own values win over any normal declaration, whatever the layer. Such a case\n needs a change in `packages/components`.\n- Depth is a surface scale, not a shadow: a lighter surface sits higher. A light palette collapses\n that scale onto white and draws depth with a shadow instead; a dark one carries it in the surfaces\n and replaces the shadow with a hard edge. Since `light-dark()` is a color function and cannot\n switch a `box-shadow` geometry, state both branches at once and switch them by their colors — the\n shadow token transparent in dark mode, the edge token transparent in light mode. A container that\n paints a surface of its own passes it down through `--kol-surface`, which reaches slotted\n components too, so their host box matches the surface they were placed on.\n\n### CSS Custom Properties and SASS Variables\n\nCSS custom properties remain part of the global cascade and are not isolated by the Shadow DOM.\nOverusing them (in theme files as well as in component styles) can collide with variables defined\non a host page, and every custom property you declare is implicitly overridable from outside,\nwhether you intended that or not.\n\n**Prefer plain CSS over a custom property.** Before adding a custom property, check whether the\nplatform already gives the consumer a way to control it — the standard box model (`width`,\n`height`), inherited properties (`color`, `font-size` via `em`), or relative units (`%`, container\nquery units). A component that simply fills its host (`width: 100%; height: 100%` inside, a sane\ndefault `width`/`height` on `:host`) can be resized with plain CSS, exactly like a native element —\nno bespoke API, no documentation burden, nothing to keep in sync. Only reach for a custom property\nwhen the value genuinely cannot be derived this way (e.g. a semantic color token that isn't just\n`currentColor`, or a value with no corresponding native CSS mechanism).\n\n**Rule:** only declare a CSS custom property when it is a deliberate, documented customization\npoint (a `--kol-<component>-<name>` design token). For anything else — internal aliases,\nintermediate values, ratios, or derived defaults — use a SASS `$variable` instead. SASS variables\nare resolved at build time, can't leak into the global cascade, and can't be overridden from a host\npage, so they can't accidentally become part of the public API.\n\nDo not introduce a second, internal custom property just to make the code more readable:\n\n```scss\n// ❌ Bad: `--color-bar` is an unintended, additional public custom property.\n// It reacts to overrides from a host page exactly like `--kol-progress-color-bar`,\n// even though only the latter was meant to be part of the API.\n.kol-progress {\n\t--color-bar: var(--kol-progress-color-bar, #0075ff);\n\n\t&__bar-progress {\n\t\tfill: var(--color-bar);\n\t}\n}\n```\n\n```scss\n// ✅ Good: the SASS variable holds the default value; the only custom property\n// is `--kol-progress-color-bar`, referenced directly wherever needed.\n$kol-progress-default-color-bar: #0075ff;\n\n.kol-progress {\n\t&__bar-progress {\n\t\tfill: var(--kol-progress-color-bar, #{$kol-progress-default-color-bar});\n\t}\n}\n```\n\nAny further unit conversion or math that doesn't depend on a runtime custom property (e.g. `to-rem()`,\nratios, breakpoints) belongs in SASS, not in an extra layer of `calc()`/custom-property indirection.\n\n`kol-avatar` is an example of preferring plain CSS: instead of a `--kol-avatar-size` custom property,\n`:host` gets a default `width` and an `aspect-ratio: 1`, and the inner element derives its size from the\nhost via container query units (`cqw`/`cqh`) instead of a separate ratio calculation. Consumers resize it\nthe same way they'd resize any block-level element — with plain `width`/`height`.\n\nThe avatar must always stay square, even if `width` and `height` end up different (e.g. both are set\nexplicitly to different values), so the inner element uses `max(100cqw, 100cqh)` for both its own `width`\nand `height` — the larger of the two wins, and `:host` centers it (`align-items`/`justify-content`), so it\nmay visually extend beyond the host on the smaller axis. Since CSS can't distinguish \"our default\" from\n\"an explicit author value\" on two independent properties, only setting `width` reliably resizes the avatar\nbelow its 100px default; setting only `height` below 100px does not shrink it, because our own default\n`width` is still in effect and wins the `max()`. This is a deliberate, documented trade-off, not a bug —\nachieving full symmetry would require either a custom property or JavaScript, both of which cost more\nthan the trade-off is worth.\n\n### SCSS Architecture Guidelines: BEM with Smart Nesting\n\nWhen writing component theme styles, follow these principles for clean, maintainable SCSS:\n\n#### 1. **Flat BEM Structure (Root Level)**\n\nAll BEM modifiers and independent elements belong at **root level** of the mixin. Never nest BEM class names:\n\n```scss\n@mixin kol-alert-theme {\n\t// ✅ All BEM selectors on root (flat)\n\t.kol-alert { ... }\n\t.kol-alert--variant-msg { ... }\n\t.kol-alert--variant-card { ... }\n\t.kol-alert--type-default { ... }\n\t.kol-alert__container { ... }\n\t.kol-alert__heading { ... }\n}\n```\n\n**Why?** BEM classnames are independent selectors. Each class should be predictable and flat.\n\n#### 2. **Contextual Nesting (When Variants Change Element Behavior)**\n\nNest **only when a modifier changes how a child element behaves**. Keep all rules for an element together:\n\n```scss\n.kol-alert__closer {\n\tplace-self: center;\n\n\t.kol-button {\n\t\tborder-radius: 50%;\n\t\twidth: var(--a11y-min-size);\n\t\theight: var(--a11y-min-size);\n\t\tcursor: pointer;\n\n\t\t// ✅ Variant changes button styling - nest here\n\t\t.kol-alert--variant-msg & {\n\t\t\t--text-color: var(--alert-accent-color);\n\t\t}\n\n\t\t.kol-alert--variant-card & {\n\t\t\t--text-color: var(--color-light);\n\t\t}\n\t}\n}\n```\n\n**Rule of thumb**: All rules for `.kol-button` in `.kol-alert__closer` stay in one place. This keeps related styles together and makes maintenance easier.\n\n#### 3. **Never Use `$root` or `@at-root`**\n\n❌ **Outdated pattern (removed):**\n\n```scss\n.kol-alert {\n\t$root: &;\n\t&__closer {\n\t\t@at-root #{$root}--variant-msg & { ... }\n\t}\n}\n```\n\n✅ **Modern pattern (direct nesting):**\n\n```scss\n.kol-alert__closer {\n\t.kol-button {\n\t\t.kol-alert--variant-msg & { ... }\n\t}\n}\n```\n\nThis is clearer and doesn't require Sass variable gymnastics.\n\n#### 4. **Structure Template**\n\n```scss\n@mixin kol-component-theme {\n\t// 1. Base component (no children)\n\t.kol-component {\n\t\tdisplay: flex;\n\t\twidth: 100%;\n\t}\n\n\t// 2. All BEM modifiers at root (flat)\n\t.kol-component--variant-a {\n\t\t...\n\t}\n\n\t.kol-component--type-default {\n\t\t...\n\t}\n\n\t// 3. Elements with contextual nesting for variants\n\t.kol-component__heading {\n\t\tfont-weight: bold;\n\n\t\t.kol-component--variant-a & {\n\t\t\tcolor: red;\n\t\t}\n\t}\n\n\t.kol-component__content {\n\t\tpadding: 1rem;\n\n\t\t.kol-component--variant-a & {\n\t\t\tbackground: white;\n\t\t}\n\t}\n\n\t// 4. Child components with variant context\n\t.kol-component__button {\n\t\t.kol-button {\n\t\t\tcursor: pointer;\n\n\t\t\t.kol-component--variant-a & {\n\t\t\t\t--text-color: var(--accent);\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### General rules for custom themes\n\n- Do not use `!important` in your styles, as this will override the styles of the basis global and component layers.\n- Do only overwrite styling definitions you will really customize. Do not set styling definitions that are already set (redundant) in the basis global and component layers, as this will override the styles of the basis global and component layers.\n- Do not `inherit` styles over the `:host` element, as this will override the styles of the basis global and component layers. This makes your component less robust from outside environment styles. Only the `kol-icon` inherits some specific styles, like `color`, `font-size`, `font-family` and `line-height`, as these are needed for the icon to be displayed correctly inline to this neighbored elements.\n- Do not set the default `font-family`, `font-size` or `box-sizing` in the basis or theme component layer (redundant), as these are already set in the basis global layers. If you need to set a different font-family or font-size, you can do this in the theme global layer.\n- Do not set `margin` or `padding` in the basis global and component layers. If you need to set a different margin or padding, you can do this in the theme global or component layers.\n- Do not use `@media (prefers-color-scheme: …)`, the `color-scheme` property or the `light-dark()` function in the basis global and component layers. Dark/light color schemes are a theme concern and belong exclusively in the theme global layer (see [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](docs/BASE_STYLING_VS_THEMING_CONCEPT.md)). `forced-colors` (high contrast) is a separate accessibility mechanism and stays in the basis `kol-forced-colors` layer.\n- Do not use `overflow: hidden` in styling or theming, as it often causes issues for reuse and should be avoided.\n- **Do not use `@layer` declarations in utility files**: Helper files, mixin files, and partial files (starting with `_`) should not contain `@layer` declarations. These files are utilities and should be layer-agnostic. This is enforced by the custom Stylelint rule `kolibri/no-layer-in-utility-files`.\n- **Never use `$root` variables or `@at-root` in component mixins**: All selectors should be explicit. Use direct child/descendant nesting only when a modifier changes element behavior within a specific context.\n\n## Samples\n\nThe samples are located in `packages/samples/react` and demonstrate how to use the components in react. Each component has its own folder and the basic sample are in `basic.tsx`. Other stories can be added in the same folder. All samples of a component are registered in the `routes.ts` file.\n\n## Coding Conventions\n\n- Formatting is enforced via **Prettier** with settings defined in `prettier.config.js` (print width 160, single quotes, tabs).\n- `.editorconfig` sets `indent_style = tab` and `max_line_length = 160` for code files. Markdown and YAML files use spaces.\n- ESLint and Stylelint are run using `pnpm lint`. Lint rules should **not** be disabled via inline comments. Instead, describe the problem and work towards a clean solution.\n- Lists and enumerations in code should be kept in alphanumeric order. This also applies to import specifiers and union type literals.\n- Do not disable ESLint, Stylelint or TypeScript rules inline. Fix the code instead of turning such rules off.\n- ESLint and Stylelint are run using `pnpm lint`.\n- Lists and enumerations in code should be kept in alphabetical order (see `docs/tutorials/NEW_COMPONENT.md`).\n- Commit messages follow the **Conventional Commits** specification.\n- See also the [Contributing Guide](CONTRIBUTING.md) for more details on coding conventions and best practices.\n- Spell \"KoliBri\" with this casing in all documentation and code. The only exception is the component named KolKolibri.\n- Use ESM import syntax in browser code and scripts whenever supported, instead of `require` imports.\n- Do not create barrel files (e.g. `index.ts` that re-export modules). Import modules directly instead.\n- Stencil component classes follow one member order: statics, `@Element`, `@State`, fields, constructor, each `@Prop`, `@Event`, `@Method`, lifecycle methods, `@Listen`, helpers, `render`; a `@Watch` directly follows the `@Prop` or `@State` it observes (see the skeleton ARC42, _Member order_; pinned by `component-structure.spec.ts`).\n- Reuse the prop definition of `internal/props` for a public prop name (e.g. `disabledProp` for every `_disabled`). Add a variant for the same render key only where it differs functionally, where a shared factory types it per component (callbacks, links, options) or where its meaning differs (`paginationLabelProp`), and document it in `internal/props/prop-keys.spec.ts`.\n- Do not place constant declarations before import statements; imports must always be at the very top of the file.\n- **Scripts must be platform-independent**: All scripts in the `scripts/` folder must work on Windows, macOS, and Linux without requiring external tools or platform-specific dependencies. Use Node.js built-in modules instead of external command-line tools like `rg`, `grep`, `find`, etc.\n- Inline code documentation follows [Inline code documentation](#inline-code-documentation).\n\n### Inline code documentation\n\nWe encourage inline code documentation (JSDoc in TypeScript/TSX, comments in SCSS and scripts), but only as much as necessary and as little as possible. This rule applies to every new or changed comment; when you touch code, bring the comments of the touched code in line with it.\n\n- **Document what the code cannot say itself**: the purpose of public API (`@Prop`, `@Method`, `@Event`, exported functions and types), constraints, a non-obvious reason (the \"why\") and known limitations.\n- **Do not repeat the code**: no comment that restates a name, a type or the next line. The TypeScript signature is the source of truth, so no `@param {string}` or `@returns {void}` type annotations.\n- **Describe the present and the future, never the past**: state what the code is and does and, where relevant, where it is heading (`@deprecated` with its replacement, a `TODO` with an issue link). Do not write history such as \"previously\", \"changed to\", \"fixed\", \"new:\", and do not refer to the diff, the pull request or a predecessor implementation. History belongs in the commit message, the pull request and the changelog. If an earlier state still matters, state the constraint that follows from it today.\n- **Write for human and AI readers alike**: clear, easy to follow and free of contradictions. One statement per fact, terms named exactly as in the code, no vague wording (\"maybe\", \"somehow\", \"for now\"). A comment never contradicts the code, another comment or the documentation. Update or delete a comment together with the code it describes, and link the authoritative document instead of copying it.\n- **Published API documentation stays stable**: the JSDoc of public `@Prop`, `@Method` and `@Event` members is published (`custom-elements.json`, `docs-vscode`, adapter IntelliSense). Refactorings and migrations keep it unchanged (see [Public API Contract](packages/components/src/components/_skeleton/ARC42.md#public-api-contract-migration-parity)); rewording it is a change of its own.\n\n```ts\n// ❌ Bad: repeats the signature and tells history.\n/**\n * Sets the label.\n * @param {string} value - the label\n * Previously this was handled by the controller; changed in the skeleton migration.\n */\nprivate setLabel(value: string): void {}\n\n// ✅ Good: states the constraint the code cannot express.\n/**\n * Runs before the first render, because the behaviors read the normalized label in `componentWillLoad`.\n */\nprivate setLabel(value: string): void {}\n```\n\n## Linting and Formatting\n\n- Run `pnpm lint` to check for linting errors across all packages. This script runs ESLint, Stylelint and TypeScript checks.\n - ⚠️ **Note**: TypeScript type checking in the lint script can require built artifacts. If you've made source code changes, lint will handle any necessary compilation. Explicit pre-build is typically unnecessary.\n - You can try to automatically fix linting issues with `pnpm lint:eslint --fix`, but this may not resolve all issues.\n- Run `pnpm format` to format all code files using Prettier. You can try to automatically fix linting issues with `pnpm format -w`, but this may not resolve all issues.\n- If your pull request only modifies Markdown files, skip `pnpm build`, `pnpm lint` and `pnpm test`. Just format the Markdown using `pnpm format` or Prettier.\n\n### Pre-commit checklist\n\n- **Always run `pnpm format` (or `pnpm --filter <package> format` for a single workspace) right before committing.** Formatting failures are one of the most common reasons for blocked quality gates, so make this the last step before `git commit` even for documentation-only changes.\n- **For SCSS changes**: Always run `pnpm lint:stylelint --fix` (or `pnpm --filter <package> lint:stylelint --fix`) to automatically correct formatting, property order, and selector structure rules before committing. This ensures compliance with BEM structure and style consistency.\n- After formatting, re-stage affected files with `git add -u` so the formatted content is what gets committed.\n\n## Testing\n\n- Run `pnpm test` from the repository root to execute all unit and integration tests.\n - ⚠️ **Note**: Test runners (Vitest, Jest, Playwright, etc.) execute an implicit build automatically before running tests. **Do NOT run a separate `pnpm build` beforehand** — this wastes time. The test scripts handle compilation and type checking internally.\n- Text snapshots of the unit tests can be updated with `pnpm test:update:unit` or via the `update-snapshots.yml` GitHub workflow. Visual screenshots are **not** committed: differences are approved on the review page of the pull request (see `docs/visual-review.md`); `pnpm snapshots:pull` fetches the current baseline for local runs.\n- Individual packages provide their own test scripts (e.g. `pnpm --filter @public-ui/components test:unit`).\n - These also perform implicit builds, so explicit pre-build is unnecessary.\n\n## Pull Request Guidelines\n\n- PR titles should be meaningful as they appear in the release notes.\n- Every PR must link to its issue and contain only changes related to that issue.\n- Ensure automated tests pass and manual testing is completed when required.\n- Update documentation or migration guides if your changes affect them.\n",
25
+ "code": "# Agent Instructions\n\nThis repository is a monorepo managed with **pnpm** and **Nx**. It contains multiple packages under `packages/` such as web components, themes, adapters, samples and tooling.\n\n## Handling hints\n\nWe have a monorepo structure with multiple packages, each with its own `package.json`. The root `package.json` contains shared dependencies and scripts. Use `pnpm` commands to manage dependencies and run scripts across packages.\n\n- To install dependencies, use `pnpm i` at the root level. This will install all dependencies for all packages.\n- If you change a dependency in a package:\n - Use only exact version numbers in `package.json`. Other peers will not be able to use the package if you can use a range version.\n - You need to run `pnpm i` at the root level. This updates the lockfile and ensures all packages are using the correct versions.\n- Never add a `packageManager` field to any `package.json` file.\n- Avoid that branch name may contain hidden characters.\n- Development workflow: `git pull` → `pnpm i` → `pnpm -r build` → `pnpm dev` only in the packages being changed → work on the code. No `dev` or `preview` script builds dependencies. Never run a build while a watcher is active, the components build clears the watcher's output. See [CONTRIBUTING.md](CONTRIBUTING.md#daily-workflow).\n- If something does not work, check in the event of an error whether all dependent submodules have been built.\n- To build a single package faster, run commands with downstream dependents using `pnpm --filter ...<package>` (e.g., `pnpm --filter ...@public-ui/sample-react build`). A package's build never builds another package: `pnpm -r build` builds each package exactly once in topological order. Build a package together with its dependencies using `pnpm --filter <package>... build` (e.g. components, which needs the kolicons font from `@public-ui/icons`).\n\n## 🚨 Format-first rule\n\n> **Stop before you commit:** run the formatter so CI never rejects your patch for style drift.\n\n1. Run `pnpm format` from the repo root whenever you change code, docs or configs.\n2. If you only touched one package, you may instead run `pnpm --filter <package> format` for a quicker pass.\n3. Re-stage the affected files (`git add -u`) so the formatted result is what lands in the commit.\n\nNo package scripts in this repo need extra flags such as `-- --write`; the scripts already know when to write changes versus just check.\n\n## Semantic Versioning\n\nThis repository follows **Semantic Versioning** (SemVer) for all packages. Each package version is defined in its own `package.json` file. The versioning scheme is as follows:\n\n- **Major version**: Incremented for incompatible API changes.\n- **Minor version**: Incremented for adding functionality in a backwards-compatible manner.\n- **Patch version**: Incremented for backwards-compatible bug fixes.\n\nThe public API of a component is its props, methods, events, slots and exported types, including their behaviour. Its internal DOM structure and the BEM classes on it are a **theming contract** instead: changing them is a **theming breaking change**, not a hard breaking change. It ships in at least a minor release, carries the label `release:theming` (changelog section _Theming_), lists the old and new classes in the pull request and adapts all themes of this repository in the same change. Theme authors adapt their themes through their own visual snapshots and the zero-visual-delta workflow. See [Theming Contract](packages/components/docs/ARC42-SKELETON.md#theming-contract-shadow-dom-structure-and-bem-classes).\n\nIf we deprecate a feature, we will mark it as deprecated in the code and documentation, but we will not remove it immediately. Instead, we will provide a migration guide (migration\\*.md) for users to transition to the new feature. Also we provide a migration tool in the `packages/tools/kolibri-cli` package to help with the migration process. You have to add a migration task from the previous version to the new version in the `packages/tools/kolibri-cli/src/migrations` folder. In the migration package, are a lot of migration tasks already implemented, so you can use them as a reference.\n\n## Project Structure\n\n- `packages/components` – Stencil based web components\n - `packages/components/src/component` – components\n - `packages/components/src/schema` – schema definitions for all components\n- `packages/samples` – sample applications demonstrating usage\n - `packages/samples/angular` – Angular sample app; do not edit\n - `packages/samples/react` – React sample app; all samples; write component samples here\n- `packages/adapters/*` – generated framework integration packages; do not edit\n- `packages/themes` – style themes and assets\n - `packages/themes/default` – primary maintained standard theme\n - All other themes are not actively maintained\n- `packages/tools/kolibri-cli` – helper CLI for migration\n- Documentation lives in `docs/`.\n- Every component that embeds another one renders that component's functional component through an item (see the skeleton ARC42, _Embedded Components (Items)_).\n- Do always ignore and do not edit all `assets` folders in all packages, as these are generated by the build process and should not be edited manually. If you need to change something in the assets, you have to change it in the source code and rebuild the package.\n\n## Theming\n\nThe theming is realized with adopted style sheets on web components and will be adopted at the mounted hook of the components. All following styling rules are only relevant for the `components` and `themes` packages.\n\n### The 5 styling layers\n\n1. **A11y Preset layer**: This layer comes out of the `adopted-style-sheets` package and contains the basic styles for accessibility. It is applied to all components.\n2. **Basis Global layer**: This layer contains the basis global styles for all components and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer. It never contains a color scheme (dark/light).\n3. **Basis Component layer**: This layer contains the basis styles for one component and comes out of the `@public-ui/components` package. It is applied only component specific layout styles without margins and paddings. Generally, the styling works without colors, as the colors should only be set through the custom Theme Layer. It never contains a color scheme (dark/light).\n4. **Theme Global layer**: This layer contains the global styles for all components of a theme and comes out of a own theme package, like `@public-ui/theme-default`. Color schemes (dark/light) are defined here via theme tokens.\n5. **Theme Component layer**: This layer contains the component specific styles for one component of a theme and comes out of a own theme package, like `@public-ui/theme-default`.\n\n> **Base styling vs. theming — dark/light lives in the theme.** The base styling of the components package (layers 1–3) is responsible for layout and structure only. It knows no dark/light color scheme: no `prefers-color-scheme`, no `color-scheme`, no `light-dark()`, no scheme tokens. Black and white in the base layers are a contrast fallback, not a color design. Dark/light theming is anchored and implemented exclusively in the theme packages (layers 4–5). See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](docs/BASE_STYLING_VS_THEMING_CONCEPT.md).\n\n### Global accessibility styles\n\n```css\n/*\n * This file contains all rules for accessibility.\n */\n@layer kol-global {\n\t:host {\n\t\t/*\n\t\t * Minimum size of interactive elements.\n\t\t */\n\t\t--a11y-min-size: #{rem(44)};\n\t\t/*\n\t\t * No element should be used without a background and font color whose contrast ratio has\n\t\t * not been checked. By initially setting the background color to white and the font color\n\t\t * to black, the contrast ratio is ensured and explicit adjustment is forced.\n\t\t */\n\t\tbackground-color: white;\n\t\tcolor: black;\n\t}\n\n\t* {\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\thyphens: auto;\n\t\t/*\n\t\t * Verdana is an accessible font that can be used without requiring additional loading time.\n\t\t */\n\t\tfont-family: Verdana;\n\t\t/*\n\t\t * Letter spacing is required for all texts.\n\t\t */\n\t\tletter-spacing: inherit;\n\t\t/*\n\t\t * This rule enables the word dividing for all texts. That is important for high zoom levels.\n\t\t */\n\t\tword-break: break-word;\n\t\t/*\n\t\t * Word spacing is required for all texts.\n\t\t */\n\t\tword-spacing: inherit;\n\t}\n\n\t/*\n\t * All interactive elements should have a minimum size of rem(44).\n\t */\n\t/* input:not([type='checkbox'], [type='radio'], [type='range']), */\n\t/* option, */\n\t/* select, */\n\t/* textarea, */\n\t[role='button'],\n\tbutton:not([role='link']),\n\t.kol-input .input {\n\t\tmin-height: var(--a11y-min-size);\n\t\tmin-width: var(--a11y-min-size);\n\t}\n\n\t/*\n\t * Some interactive elements should not inherit the font-family and font-size.\n\t */\n\ta,\n\tbutton,\n\th1,\n\th2,\n\th3,\n\th4,\n\th5,\n\th6,\n\tinput,\n\toption,\n\tselect,\n\ttextarea {\n\t\t/*\n\t\t * All elements should inherit the font family from his parent element.\n\t\t */\n\t\tfont-family: inherit;\n\t\t/*\n\t\t * All elements should inherit the font size from his parent element.\n\t\t */\n\t\tfont-size: inherit;\n\t}\n}\n\n/**\n * Sometimes we need the semantic element for accessibility reasons,\n * but we don't want to show it.\n *\n * - https://www.a11yproject.com/posts/how-to-hide-content/\n */\n.visually-hidden {\n\tclip: rect(0 0 0 0);\n\tclip-path: inset(50%);\n\theight: 1px;\n\toverflow: hidden;\n\tposition: absolute;\n\twhite-space: nowrap;\n\twidth: 1px;\n}\n```\n\n### Styling rules\n\nThe basis global layer set the default font-size and box-sizing for all components.\n\n```css\n@layer kol-global {\n\t:host {\n\t\tfont-size: rem(16);\n\t\t/*\n\t\t * The max-width is needed to prevent the table from overflowing the\n\t\t * parent node, if the table is wider than the parent node.\n\t\t */\n\t\tmax-width: 100%;\n\t}\n\n\t* {\n\t\t/*\n\t\t * We prefer to box-sizing: border-box for all elements.\n\t\t */\n\t\tbox-sizing: border-box;\n\t}\n ...\n}\n```\n\n### Custom Theming rules\n\nThe custom theme layer is used to set the colors and other theme specific styles. The custom theme layer should not contain any layout styles, as these are already set in the basis global and component layers.\n\nDark/light color schemes are implemented in the theme layers only. Define all colors that differ between light and dark as tokens on `:host` in the theme global layer and switch the scheme there (`color-scheme` + `light-dark()`, `@media (prefers-color-scheme: dark)`, or an opt-in attribute). The theme component layer only references those tokens and never contains its own scheme media queries. Alternatively, a theme may ship a separate dark export that is registered as an additional theme and switched via the `kol-theme` attribute. The base styling of the components package must never be involved in this.\n\nFor example, generally the font-family is set in the theme global layer, on the `:host` element, so that all components inherit the font-family from the theme. The font-size is set in the basis global layer, so that all components inherit the font-size from the basis global layer. But it is possible to set a other base font-size in the theme global layer, if needed.\n\n```css\n@layer kol-theme-global {\n\t:host {\n\t\t--font-family: var(--kolibri-font-family, Verdana, Arial, Calibri, Helvetica, sans-serif);\n\t\t--font-size: var(--kolibri-font-size, #{rem(16)});\n ...\n\t}\n\n\t:host {\n\t\tfont-size: var(--font-size);\n\n\t\t* {\n\t\t\tfont-family: var(--font-family);\n\t\t}\n\t}\n ...\n}\n```\n\nIn the theme component layer, you can set what ever you need to realize your own custom style guidelines. For example, you can set the colors, borders, shadows, etc. for the component.\n\n```css\n@layer kol-theme-component {\n ...\n}\n```\n\n### Color schemes\n\nA theme carries one palette per color scheme in a single declaration, resolved by the CSS\n`light-dark()` function:\n\n```scss\n@layer kol-theme-global {\n\t:host {\n\t\t--color-text: var(--kolibri-color-text, light-dark(#202020, #{$dark-color-text}));\n\t}\n}\n```\n\nRules that hold for every theme:\n\n- **Never declare `color-scheme` in a theme**, and never write `@media (prefers-color-scheme: …)`.\n `color-scheme` is an inherited property and inheritance follows the flat tree, so it crosses the\n shadow boundary on its own: each component resolves `light-dark()` against whatever the consuming\n application has in effect where the component sits. A declaration on `:host` would replace that\n inherited value, and the page and the components in it could then disagree — which is exactly the\n bug this rule exists to prevent.\n- The application owns the scheme, in plain CSS: `:root { color-scheme: light dark }` to follow the\n operating system, `color-scheme: dark` on any element to force a subtree. Consequently an\n application that declares nothing stays light, whatever the operating system says. Dark mode is\n opt-in; `color-scheme.css` in a theme package ships that one line plus the page colors.\n- Sass does not evaluate variables inside `var()`. Interpolate them (`#{$dark-color-text}`).\n- An application stylesheet that uses `light-dark()` must not be downlevelled. A CSS minifier\n targeting older browsers rewrites it into a `prefers-color-scheme` media query with space\n toggles, and that replacement ignores the `color-scheme` property. A theme's CSS is a string\n adopted into the shadow roots at runtime and is never processed by the application's CSS\n pipeline, so the page would follow the operating system while the components follow\n `color-scheme`. Both sample host apps therefore pin `build.cssTarget` in their Vite config.\n- The base layer hardcodes `black` and `white` in a few places. Where it routes them through a\n token, override the token (`--kol-a11y-font-color` / `--kol-a11y-background-color` in `a11y.scss`\n are the sanctioned hook for the host box of every component); elsewhere restate the declaration in\n a theme layer, which sits above `kol-a11y`, `kol-global` and `kol-component`. Keep the light\n branch byte identical to the base value so no light snapshot moves.\n- What a theme layer cannot reach are the color stops of a `@keyframes` rule declared in the base\n layer: an animation's own values win over any normal declaration, whatever the layer. Such a case\n needs a change in `packages/components`.\n- Depth is a surface scale, not a shadow: a lighter surface sits higher. A light palette collapses\n that scale onto white and draws depth with a shadow instead; a dark one carries it in the surfaces\n and replaces the shadow with a hard edge. Since `light-dark()` is a color function and cannot\n switch a `box-shadow` geometry, state both branches at once and switch them by their colors — the\n shadow token transparent in dark mode, the edge token transparent in light mode. A container that\n paints a surface of its own passes it down through `--kol-surface`, which reaches slotted\n components too, so their host box matches the surface they were placed on.\n\n### CSS Custom Properties and SASS Variables\n\nCSS custom properties remain part of the global cascade and are not isolated by the Shadow DOM.\nOverusing them (in theme files as well as in component styles) can collide with variables defined\non a host page, and every custom property you declare is implicitly overridable from outside,\nwhether you intended that or not.\n\n**Prefer plain CSS over a custom property.** Before adding a custom property, check whether the\nplatform already gives the consumer a way to control it — the standard box model (`width`,\n`height`), inherited properties (`color`, `font-size` via `em`), or relative units (`%`, container\nquery units). A component that simply fills its host (`width: 100%; height: 100%` inside, a sane\ndefault `width`/`height` on `:host`) can be resized with plain CSS, exactly like a native element —\nno bespoke API, no documentation burden, nothing to keep in sync. Only reach for a custom property\nwhen the value genuinely cannot be derived this way (e.g. a semantic color token that isn't just\n`currentColor`, or a value with no corresponding native CSS mechanism).\n\n**Rule:** only declare a CSS custom property when it is a deliberate, documented customization\npoint (a `--kol-<component>-<name>` design token). For anything else — internal aliases,\nintermediate values, ratios, or derived defaults — use a SASS `$variable` instead. SASS variables\nare resolved at build time, can't leak into the global cascade, and can't be overridden from a host\npage, so they can't accidentally become part of the public API.\n\nDo not introduce a second, internal custom property just to make the code more readable:\n\n```scss\n// ❌ Bad: `--color-bar` is an unintended, additional public custom property.\n// It reacts to overrides from a host page exactly like `--kol-progress-color-bar`,\n// even though only the latter was meant to be part of the API.\n.kol-progress {\n\t--color-bar: var(--kol-progress-color-bar, #0075ff);\n\n\t&__bar-progress {\n\t\tfill: var(--color-bar);\n\t}\n}\n```\n\n```scss\n// ✅ Good: the SASS variable holds the default value; the only custom property\n// is `--kol-progress-color-bar`, referenced directly wherever needed.\n$kol-progress-default-color-bar: #0075ff;\n\n.kol-progress {\n\t&__bar-progress {\n\t\tfill: var(--kol-progress-color-bar, #{$kol-progress-default-color-bar});\n\t}\n}\n```\n\nAny further unit conversion or math that doesn't depend on a runtime custom property (e.g. `to-rem()`,\nratios, breakpoints) belongs in SASS, not in an extra layer of `calc()`/custom-property indirection.\n\n`kol-avatar` is an example of preferring plain CSS: instead of a `--kol-avatar-size` custom property,\n`:host` gets a default `width` and an `aspect-ratio: 1`, and the inner element derives its size from the\nhost via container query units (`cqw`/`cqh`) instead of a separate ratio calculation. Consumers resize it\nthe same way they'd resize any block-level element — with plain `width`/`height`.\n\nThe avatar must always stay square, even if `width` and `height` end up different (e.g. both are set\nexplicitly to different values), so the inner element uses `max(100cqw, 100cqh)` for both its own `width`\nand `height` — the larger of the two wins, and `:host` centers it (`align-items`/`justify-content`), so it\nmay visually extend beyond the host on the smaller axis. Since CSS can't distinguish \"our default\" from\n\"an explicit author value\" on two independent properties, only setting `width` reliably resizes the avatar\nbelow its 100px default; setting only `height` below 100px does not shrink it, because our own default\n`width` is still in effect and wins the `max()`. This is a deliberate, documented trade-off, not a bug —\nachieving full symmetry would require either a custom property or JavaScript, both of which cost more\nthan the trade-off is worth.\n\n### SCSS Architecture Guidelines: BEM with Smart Nesting\n\nWhen writing component theme styles, follow these principles for clean, maintainable SCSS:\n\n#### 1. **Flat BEM Structure (Root Level)**\n\nAll BEM modifiers and independent elements belong at **root level** of the mixin. Never nest BEM class names:\n\n```scss\n@mixin kol-alert-theme {\n\t// ✅ All BEM selectors on root (flat)\n\t.kol-alert { ... }\n\t.kol-alert--variant-msg { ... }\n\t.kol-alert--variant-card { ... }\n\t.kol-alert--type-default { ... }\n\t.kol-alert__container { ... }\n\t.kol-alert__heading { ... }\n}\n```\n\n**Why?** BEM classnames are independent selectors. Each class should be predictable and flat.\n\n#### 2. **Contextual Nesting (When Variants Change Element Behavior)**\n\nNest **only when a modifier changes how a child element behaves**. Keep all rules for an element together:\n\n```scss\n.kol-alert__closer {\n\tplace-self: center;\n\n\t.kol-button {\n\t\tborder-radius: 50%;\n\t\twidth: var(--a11y-min-size);\n\t\theight: var(--a11y-min-size);\n\t\tcursor: pointer;\n\n\t\t// ✅ Variant changes button styling - nest here\n\t\t.kol-alert--variant-msg & {\n\t\t\t--text-color: var(--alert-accent-color);\n\t\t}\n\n\t\t.kol-alert--variant-card & {\n\t\t\t--text-color: var(--color-light);\n\t\t}\n\t}\n}\n```\n\n**Rule of thumb**: All rules for `.kol-button` in `.kol-alert__closer` stay in one place. This keeps related styles together and makes maintenance easier.\n\n#### 3. **Never Use `$root` or `@at-root`**\n\n❌ **Outdated pattern (removed):**\n\n```scss\n.kol-alert {\n\t$root: &;\n\t&__closer {\n\t\t@at-root #{$root}--variant-msg & { ... }\n\t}\n}\n```\n\n✅ **Modern pattern (direct nesting):**\n\n```scss\n.kol-alert__closer {\n\t.kol-button {\n\t\t.kol-alert--variant-msg & { ... }\n\t}\n}\n```\n\nThis is clearer and doesn't require Sass variable gymnastics.\n\n#### 4. **Structure Template**\n\n```scss\n@mixin kol-component-theme {\n\t// 1. Base component (no children)\n\t.kol-component {\n\t\tdisplay: flex;\n\t\twidth: 100%;\n\t}\n\n\t// 2. All BEM modifiers at root (flat)\n\t.kol-component--variant-a {\n\t\t...\n\t}\n\n\t.kol-component--type-default {\n\t\t...\n\t}\n\n\t// 3. Elements with contextual nesting for variants\n\t.kol-component__heading {\n\t\tfont-weight: bold;\n\n\t\t.kol-component--variant-a & {\n\t\t\tcolor: red;\n\t\t}\n\t}\n\n\t.kol-component__content {\n\t\tpadding: 1rem;\n\n\t\t.kol-component--variant-a & {\n\t\t\tbackground: white;\n\t\t}\n\t}\n\n\t// 4. Child components with variant context\n\t.kol-component__button {\n\t\t.kol-button {\n\t\t\tcursor: pointer;\n\n\t\t\t.kol-component--variant-a & {\n\t\t\t\t--text-color: var(--accent);\n\t\t\t}\n\t\t}\n\t}\n}\n```\n\n### General rules for custom themes\n\n- Do not use `!important` in your styles, as this will override the styles of the basis global and component layers.\n- Do only overwrite styling definitions you will really customize. Do not set styling definitions that are already set (redundant) in the basis global and component layers, as this will override the styles of the basis global and component layers.\n- Do not `inherit` styles over the `:host` element, as this will override the styles of the basis global and component layers. This makes your component less robust from outside environment styles. Only the `kol-icon` inherits some specific styles, like `color`, `font-size`, `font-family` and `line-height`, as these are needed for the icon to be displayed correctly inline to this neighbored elements.\n- Do not set the default `font-family`, `font-size` or `box-sizing` in the basis or theme component layer (redundant), as these are already set in the basis global layers. If you need to set a different font-family or font-size, you can do this in the theme global layer.\n- Do not set `margin` or `padding` in the basis global and component layers. If you need to set a different margin or padding, you can do this in the theme global or component layers.\n- Do not use `@media (prefers-color-scheme: …)`, the `color-scheme` property or the `light-dark()` function in the basis global and component layers. Dark/light color schemes are a theme concern and belong exclusively in the theme global layer (see [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](docs/BASE_STYLING_VS_THEMING_CONCEPT.md)). `forced-colors` (high contrast) is a separate accessibility mechanism and stays in the basis `kol-forced-colors` layer.\n- Do not use `overflow: hidden` in styling or theming, as it often causes issues for reuse and should be avoided.\n- **Do not use `@layer` declarations in utility files**: Helper files, mixin files, and partial files (starting with `_`) should not contain `@layer` declarations. These files are utilities and should be layer-agnostic. This is enforced by the custom Stylelint rule `kolibri/no-layer-in-utility-files`.\n- **Never use `$root` variables or `@at-root` in component mixins**: All selectors should be explicit. Use direct child/descendant nesting only when a modifier changes element behavior within a specific context.\n\n## Samples\n\nThe samples are located in `packages/samples/react` and demonstrate how to use the components in react. Each component has its own folder and the basic sample are in `basic.tsx`. Other stories can be added in the same folder. All samples of a component are registered in the `routes.ts` file.\n\n## Coding Conventions\n\n- Formatting is enforced via **Prettier** with settings defined in `prettier.config.js` (print width 160, single quotes, tabs).\n- `.editorconfig` sets `indent_style = tab` and `max_line_length = 160` for code files. Markdown and YAML files use spaces.\n- ESLint and Stylelint are run using `pnpm lint`. Lint rules should **not** be disabled via inline comments. Instead, describe the problem and work towards a clean solution.\n- Lists and enumerations in code should be kept in alphanumeric order. This also applies to import specifiers and union type literals.\n- Do not disable ESLint, Stylelint or TypeScript rules inline. Fix the code instead of turning such rules off.\n- ESLint and Stylelint are run using `pnpm lint`.\n- Lists and enumerations in code should be kept in alphabetical order (see `docs/tutorials/NEW_COMPONENT.md`).\n- Commit messages follow the **Conventional Commits** specification.\n- See also the [Contributing Guide](CONTRIBUTING.md) for more details on coding conventions and best practices.\n- Spell \"KoliBri\" with this casing in all documentation and code. The only exception is the component named KolKolibri.\n- Use ESM import syntax in browser code and scripts whenever supported, instead of `require` imports.\n- Do not create barrel files (e.g. `index.ts` that re-export modules). Import modules directly instead.\n- **Exception — prop barrels:** Prop definitions (`src/internal/props/index.ts`) and schema types (`src/schema/props/index.ts`) are deliberately imported via their barrels: one import line covers a family of related modules, and the rule `kolibri/require-barrel-import` enforces it. Nothing else gets a barrel.\n- Stencil component classes follow one member order: statics, `@Element`, `@State`, fields, constructor, each `@Prop`, `@Event`, `@Method`, lifecycle methods, `@Listen`, helpers, `render`; a `@Watch` directly follows the `@Prop` or `@State` it observes (see the skeleton ARC42, _Member order_; pinned by `component-structure.spec.ts`).\n- Reuse the prop definition of `internal/props` for a public prop name (e.g. `disabledProp` for every `_disabled`). Add a variant for the same render key only where it differs functionally, where a shared factory types it per component (callbacks, links, options) or where its meaning differs (`labelWithExpertSlotProp` beside `labelProp`), and document it in `internal/props/prop-keys.spec.ts`.\n- Document a prop variant's meaning once, at its type definition in `src/schema/props`. Component JSDocs and public-api pins reference the type instead of restating the meaning in their own words, so the texts cannot drift apart.\n- The expert-slot sentinel of a label is the empty string `''`, never `false`: only `LabelWithExpertSlotPropType` accepts it, `labelProp` and `labelLangSegmentsProp` reject it.\n- Optional `@Prop`s carry an explicit `= undefined` initializer as the documented \"no default\" contract and required `@Prop`s carry none (enforced by the ESLint rules `kolibri/prop-optional-requires-initializer` and `kolibri/prop-required-no-initializer`).\n- Do not place constant declarations before import statements; imports must always be at the very top of the file.\n- **Scripts must be platform-independent**: All scripts in the `scripts/` folder must work on Windows, macOS, and Linux without requiring external tools or platform-specific dependencies. Use Node.js built-in modules instead of external command-line tools like `rg`, `grep`, `find`, etc.\n- Inline code documentation follows [Inline code documentation](#inline-code-documentation).\n\n### Inline code documentation\n\nWe encourage inline code documentation (JSDoc in TypeScript/TSX, comments in SCSS and scripts), but only as much as necessary and as little as possible. This rule applies to every new or changed comment; when you touch code, bring the comments of the touched code in line with it.\n\n- **Document what the code cannot say itself**: the purpose of public API (`@Prop`, `@Method`, `@Event`, exported functions and types), constraints, a non-obvious reason (the \"why\") and known limitations.\n- **Do not repeat the code**: no comment that restates a name, a type or the next line. The TypeScript signature is the source of truth, so no `@param {string}` or `@returns {void}` type annotations.\n- **Describe the present and the future, never the past**: state what the code is and does and, where relevant, where it is heading (`@deprecated` with its replacement, a `TODO` with an issue link). Do not write history such as \"previously\", \"changed to\", \"fixed\", \"new:\", and do not refer to the diff, the pull request or a predecessor implementation. History belongs in the commit message, the pull request and the changelog. If an earlier state still matters, state the constraint that follows from it today.\n- **State the rule, not its origin**: a comment describes the current behaviour, never justifies it against a former mistake or an alternative. \"The predecessor accepted X\", \"keeps Y valid that Z would have rejected\" and \"X, not X\" phrasings are history dressed as reasoning — the reader needs the rule, not the deliberation.\n\n ```ts\n // ❌ Bad: justifies the present against a past mistake and an alternative.\n // `labelProp`, not `labelWithExpertSlotProp`: the predecessor's validateLabel accepted any\n // string; labelProp would reject one-character labels.\n\n // ✅ Good: the rule, in present tense.\n // The label names a landmark without an expert slot.\n ```\n\n- **Write for human and AI readers alike**: clear, easy to follow and free of contradictions. One statement per fact, terms named exactly as in the code, no vague wording (\"maybe\", \"somehow\", \"for now\"). A comment never contradicts the code, another comment or the documentation. Update or delete a comment together with the code it describes, and link the authoritative document instead of copying it.\n- **Published API documentation stays stable**: the JSDoc of public `@Prop`, `@Method` and `@Event` members is published (`custom-elements.json`, `docs-vscode`, adapter IntelliSense). Refactorings and migrations keep it unchanged (see [Public API Contract](packages/components/docs/ARC42-SKELETON.md#public-api-contract-migration-parity)); rewording it is a change of its own.\n\n```ts\n// ❌ Bad: repeats the signature and tells history.\n/**\n * Sets the label.\n * @param {string} value - the label\n * Previously this was handled by the controller; changed in the skeleton migration.\n */\nprivate setLabel(value: string): void {}\n\n// ✅ Good: states the constraint the code cannot express.\n/**\n * Runs before the first render, because the behaviors read the normalized label in `componentWillLoad`.\n */\nprivate setLabel(value: string): void {}\n```\n\n## Linting and Formatting\n\n- Run `pnpm lint` to check for linting errors across all packages. This script runs ESLint, Stylelint and TypeScript checks.\n - ⚠️ **Note**: TypeScript type checking in the lint script can require built artifacts. If you've made source code changes, lint will handle any necessary compilation. Explicit pre-build is typically unnecessary.\n - You can try to automatically fix linting issues with `pnpm lint:eslint --fix`, but this may not resolve all issues.\n- Run `pnpm format` to format all code files using Prettier. You can try to automatically fix linting issues with `pnpm format -w`, but this may not resolve all issues.\n- If your pull request only modifies Markdown files, skip `pnpm build`, `pnpm lint` and `pnpm test`. Just format the Markdown using `pnpm format` or Prettier.\n\n### Pre-commit checklist\n\n- **Always run `pnpm format` (or `pnpm --filter <package> format` for a single workspace) right before committing.** Formatting failures are one of the most common reasons for blocked quality gates, so make this the last step before `git commit` even for documentation-only changes.\n- **For SCSS changes**: Always run `pnpm lint:stylelint --fix` (or `pnpm --filter <package> lint:stylelint --fix`) to automatically correct formatting, property order, and selector structure rules before committing. This ensures compliance with BEM structure and style consistency.\n- After formatting, re-stage affected files with `git add -u` so the formatted content is what gets committed.\n\n## Testing\n\n- Run `pnpm test` from the repository root to execute all unit and integration tests.\n - ⚠️ **Note**: Test runners (Vitest, Jest, Playwright, etc.) execute an implicit build automatically before running tests. **Do NOT run a separate `pnpm build` beforehand** — this wastes time. The test scripts handle compilation and type checking internally.\n- Text snapshots of the unit tests can be updated with `pnpm test:update:unit` or via the `update-snapshots.yml` GitHub workflow. Visual screenshots are **not** committed: differences are approved on the review page of the pull request (see `docs/visual-review.md`); `pnpm snapshots:pull` fetches the current baseline for local runs.\n- Individual packages provide their own test scripts (e.g. `pnpm --filter @public-ui/components test:unit`).\n - These also perform implicit builds, so explicit pre-build is unnecessary.\n\n## Pull Request Guidelines\n\n- PR titles should be meaningful as they appear in the release notes.\n- Every PR must link to its issue and contain only changes related to that issue.\n- Ensure automated tests pass and manual testing is completed when required.\n- Update documentation or migration guides if your changes affect them.\n",
26
26
  "kind": "doc"
27
27
  },
28
28
  {
@@ -274,7 +274,7 @@
274
274
  "name": "BASE_STYLING_VS_THEMING_CONCEPT",
275
275
  "description": "Beschreibt die Abgrenzung zwischen dem Basis-Styling der Komponenten (@public-ui/components) und dem Theming in den Theme-Paketen (@public-ui/theme-*) – mit dem klaren Grundsatz, dass Dark/Light-Color-Schemes ausschließlich im Theme verankert werden.",
276
276
  "path": "docs/BASE_STYLING_VS_THEMING_CONCEPT.md",
277
- "code": "# Basis-Styling vs. Theming Konzept\n\nBeschreibt die Abgrenzung zwischen dem Basis-Styling der Komponenten (`@public-ui/components`) und dem Theming in den Theme-Paketen (`@public-ui/theme-*`) – mit dem klaren Grundsatz, dass Dark/Light-Color-Schemes ausschließlich im Theme verankert werden.\n\n## Status\n\n- Ist: Das Basis-Styling in `packages/components/src` ist scheme-frei – dort gibt es weder `prefers-color-scheme` noch `color-scheme` oder `light-dark()`. `@public-ui/theme-default` implementiert seit [#10831](https://github.com/public-ui/kolibri/pull/10831) ein Dark Color Scheme über `light-dark()` und `color-scheme.css`; alle übrigen Themes liefern bisher nur eine helle Palette.\n- Soll: Die Abgrenzung ist verbindlich festgeschrieben und in allen Konzepten, Agenten-Anweisungen und Skills verankert (siehe [Abschnitt 8](#8-verankerung-in-den-bestehenden-konzepten)). Zukünftige Dark/Light-Umsetzungen entstehen ausschließlich in den Theme-Paketen.\n\n## 1. Leitsatz\n\n> **Das Basis-Styling in `@public-ui/components` (Layer `kol-a11y`, `kol-global`, `kol-component`) ist ausschließlich für Layout und Struktur zuständig. Es kennt kein Dark/Light-Color-Scheme: kein `prefers-color-scheme`, kein `color-scheme`, kein `light-dark()`, keine Scheme-Tokens und keine Scheme-Modifier. Schwarz und Weiß in der Basis sind ein Kontrast-Fallback, keine Farbgestaltung. Dark/Light-Theming wird ausschließlich in den Theme-Paketen (Layer `kol-theme-global`, `kol-theme-component`) verankert und umgesetzt.**\n\nDer Fokus der Basis liegt auf dem Layout. Der Fokus der Themes liegt auf der Optik – dazu gehören alle Farbkombinationen, also auch die Entscheidung für ein helles oder dunkles Erscheinungsbild.\n\n## 2. Ziel\n\n- Komponenten funktionieren strukturell in jedem Theme identisch. Ein Theme-Wechsel ändert nie das Layout.\n- Themes tragen die vollständige visuelle Verantwortung. Ein Theme kann hell, dunkel oder beides anbieten, ohne dass das Komponenten-Paket angefasst werden muss.\n- Die Basis bleibt scheme-neutral. Das `unstyled`-Theme (`packages/unstyled/theme.ts`) rendert nur den Basis-Layer und muss unter der Browser-Einstellung `light` und `dark` identisch aussehen.\n- Es gibt genau eine Stelle, an der Farbentscheidungen getroffen werden. Das vermeidet Konflikte zwischen Basis-Farben und Theme-Farben und hält die Kontrastprüfung (WCAG) beim Theme.\n\n## 3. Verantwortlichkeiten je Schicht\n\nDie Layer-Reihenfolge ist in `packages/components/src/components/_layer-order.scss` definiert:\n\n```scss\n@layer kol-a11y, kol-global, kol-component, kol-theme-global, kol-theme-component, kol-forced-colors, kol-theme-forced-colors;\n```\n\n| Layer | Paket | Zuständig für | Ausdrücklich nicht zuständig für |\n| ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |\n| `kol-a11y` | `@public-ui/components` | Barrierefreiheits-Baseline: Mindestgrößen, Schriftvererbung, Schwarz/Weiß als Kontrast-Fallback | Farbgestaltung, Color Schemes |\n| `kol-global` | `@public-ui/components` | Globale Layout-Defaults: `box-sizing`, Basis-`font-size`, Resets | Farben, Abstände (`margin`, `padding`, `gap`), Color Schemes |\n| `kol-component` | `@public-ui/components` | Komponenten-Layout: Display, Flex/Grid, Position, Dimensionen, strukturelle Typografie | Farben (außer Schwarz/Weiß-Fallback), Abstände, Schatten, Rahmen-Optik, Color Schemes |\n| `kol-theme-global` | `@public-ui/theme-*` | Design-Tokens (Farben, Schriften, Abstände, Radien), **Color Schemes (Light/Dark)**, Fokus-Optik | Layout-Regeln, die bereits in der Basis stehen |\n| `kol-theme-component` | `@public-ui/theme-*` | Komponentenspezifische Optik: Farben, Rahmen, Schatten, Abstände über Tokens | Layout-Regeln der Basis, eigene Scheme-Media-Queries pro Komponente |\n| `kol-forced-colors` | `@public-ui/components` | Barrierefreiheit unter `forced-colors: active` mit System-Farbschlüsselwörtern | Dark Mode (siehe [Abschnitt 5](#5-abgrenzung-forced-colors-ist-kein-dark-mode)) |\n| `kol-theme-forced-colors` | `@public-ui/theme-*` | Theme-spezifische Ergänzungen für Forced Colors | Dark Mode |\n\nDie Verbotsliste für das Komponenten-Paket steht in [`CODE_STYLE_AND_CONVENTIONS.md`](./CODE_STYLE_AND_CONVENTIONS.md). Die fünf Styling-Schichten sind in [`AGENTS.md`](../AGENTS.md#theming) und in der arc42-Dokumentation ([ADR-008](./arc42/09-architecture-decisions.md#adr-008-five-layer-styling-architecture)) beschrieben.\n\n## 4. Dark/Light: Regeln\n\n### 4.1 Komponenten-Paket (`packages/components`)\n\nIn den Basis-Layern sind verboten:\n\n- `@media (prefers-color-scheme: …)` in jeder Form\n- die CSS-Eigenschaft `color-scheme`\n- die CSS-Funktion `light-dark()`\n- Custom Properties, deren Wert vom Scheme abhängt (z. B. `--kol-…-dark`)\n- Scheme-Modifier im Markup oder in BEM-Klassen (z. B. `kol-button--dark`)\n- Props oder States, die ein Color Scheme transportieren\n\nBegründung:\n\n1. Die Basis hat den Fokus auf Layout. Jede Farbentscheidung wäre eine Design-Entscheidung, die nur das Theme treffen darf.\n2. Ein Scheme in der Basis würde mit den Farben jedes Themes kollidieren und die Kontrastprüfung vom Theme zurück in die Basis verlagern.\n3. Das `unstyled`-Theme muss als scheme-neutrale Baseline unter `light` und `dark` identische Snapshots liefern. Nur so bleibt es ein verlässlicher Indikator für DOM-Umbauten (siehe `.claude/skills/zero-visual-delta-handoff/SKILL.md`, Fallstricke).\n\nErlaubt bleibt der Kontrast-Fallback aus dem A11y-Preset: `background-color: white; color: black`. Diese Werte sind keine Farbgestaltung, sondern erzwingen ein geprüftes Kontrastverhältnis, bis ein Theme die Farben setzt. Bestehende `white`/`black`-Stellen in der Basis (z. B. `@shared/_table-stateless.mixin.scss`, `input-checkbox/style.scss`) sind Fallbacks in diesem Sinn und werden nicht in Scheme-Logik überführt.\n\n### 4.2 Theme-Pakete (`packages/themes/*`)\n\nDark/Light wird vollständig im Theme umgesetzt. Empfohlenes Muster:\n\n1. **Tokens im globalen Theme-Layer auf `:host`** – wie heute in `packages/themes/default/src/global.scss`. Alle Farben, die sich zwischen Light und Dark unterscheiden, sind Tokens (`--color-…`), niemals Literale in Komponenten-Styles.\n2. **Scheme-Umschaltung an einer Stelle** – ebenfalls im Layer `kol-theme-global`:\n - automatisch per `color-scheme: light dark` und `light-dark()` in den Token-Werten, oder\n - per `@media (prefers-color-scheme: dark)` mit überschriebenen Tokens, oder\n - per Opt-in über ein Attribut oder eine Klasse am Host, wenn Anwendungen das Scheme selbst steuern sollen.\n3. **Komponenten-Theme-Layer referenziert nur Tokens.** Keine Scheme-Media-Queries pro Komponente. Ändert sich das Scheme, ändern sich nur die Token-Werte.\n4. **Alternative: eigener Theme-Export.** Ein Theme kann zusätzlich einen dunklen Export (z. B. `DEFAULT_DARK`) bereitstellen, der über `register([DEFAULT, DEFAULT_DARK], …)` registriert und zur Laufzeit über das Attribut `kol-theme` umgeschaltet wird (siehe [`HOWTO_REGISTER_COMPONENTS_AND_THEMES.md`](./HOWTO_REGISTER_COMPONENTS_AND_THEMES.md) und arc42 [§6.4 Theme Switching](./arc42/06-runtime-view.md#64-theme-switching)).\n\nBeispiel für Variante 2a im globalen Theme-Layer:\n\n```scss\n@layer kol-theme-global {\n\t:host {\n\t\tcolor-scheme: light dark;\n\t\t--color-text: var(--kolibri-color-text, light-dark(#202020, #f2f3f4));\n\t\t--color-light: var(--kolibri-color-light, light-dark(#ffffff, #1a1a1a));\n\t}\n}\n```\n\nKontrastanforderungen (mindestens 4,5:1 für Text, 3:1 für UI-Komponenten, siehe arc42 [Kapitel 8](./arc42/08-cross-cutting-concepts.md)) gelten für jedes Scheme einzeln und werden vom Theme nachgewiesen.\n\n## 5. Abgrenzung: Forced Colors ist kein Dark Mode\n\n`packages/components/src/components/forced-colors.scss` (Layer `kol-forced-colors`) reagiert auf `@media (forced-colors: active)` und verwendet System-Farbschlüsselwörter wie `Canvas`, `CanvasText`, `ButtonText` oder `Highlight`. Das ist ein Barrierefreiheitsmechanismus für Hochkontrast-Modi des Betriebssystems, keine Gestaltung: Das System liefert die Farben, die Basis stellt nur sicher, dass Struktur und Zustände sichtbar bleiben.\n\nDeshalb bleibt Forced Colors in der Basis erlaubt, während Dark/Light-Schemes ausgeschlossen sind. Die beiden Mechanismen dürfen nicht vermischt werden: `forced-colors` ist kein Ersatz für `prefers-color-scheme` und umgekehrt.\n\n## 6. Entscheidungsregel für Regelverschiebungen\n\nDer Skill `theme-redundancy-check` verschiebt redundante Regeln aus Themes in die Basis. Zusätzlich zur bestehenden Frage „Würde sich die Regel beim Wechsel eines Themes visuell ändern?“ gilt:\n\n> **Würde sich der Wert beim Wechsel Light ↔ Dark ändern?** Ja → die Regel bleibt im Theme. Nein → Kandidat für die Basis.\n\nJede Farbe ist damit automatisch Theme-Sache. Layout-Regeln, die in beiden Schemes gleich sind, sind Basis-Kandidaten.\n\n## 7. Nachweis und Tests\n\n- `packages/unstyled` ist die scheme-neutrale Baseline. Der visuelle Test-Harness unterstützt `KOLIBRI_VISUAL_TESTS_COLOR_SCHEME=light|dark` (`packages/tools/visual-tests/playwright.config.js`). Ein Lauf des `unstyled`-Checks unter `dark` muss gegen die `light`-Baselines 0 Diffs liefern. Das ist der Beweis, dass die Basis kein Scheme kennt.\n- Für Themes, die Dark/Light anbieten, werden Snapshots pro Scheme geführt. Das Layout muss zwischen beiden Snapshot-Sätzen pixelgleich bleiben; nur Farben dürfen sich unterscheiden.\n- Stichprobe für das Komponenten-Paket: eine Suche nach `prefers-color-scheme`, `color-scheme` und `light-dark(` in `packages/components/src` muss leer bleiben.\n\n## 8. Verankerung in den bestehenden Konzepten\n\nDer Leitsatz aus [Abschnitt 1](#1-leitsatz) ist an folgenden Stellen eingearbeitet:\n\n- [`AGENTS.md`](../AGENTS.md#theming): Styling-Schichten, Custom-Theming-Regeln und allgemeine Theme-Regeln.\n- [`docs/CODE_STYLE_AND_CONVENTIONS.md`](./CODE_STYLE_AND_CONVENTIONS.md): Verbotsliste für das Komponenten-Paket, Zuständigkeit der Themes.\n- [`packages/components/AGENTS.md`](../packages/components/AGENTS.md) und [`packages/components/src/components/README.md`](../packages/components/src/components/README.md): Styling-Grenze für Komponenten.\n- [`packages/themes/AGENTS.md`](../packages/themes/AGENTS.md): Dark/Light als Theme-Verantwortung.\n- arc42 (EN und DE): [Lösungsstrategie](./arc42/04-solution-strategy.md), [Bausteinsicht](./arc42/05-building-block-view.md), [Architekturentscheidungen](./arc42/09-architecture-decisions.md) (ADR-008, ADR-018), [Qualitätsanforderungen](./arc42/10-quality-requirements.md) (Szenario P3), [Glossar](./arc42/12-glossary.md).\n- [`docs/HOWTO_REGISTER_COMPONENTS_AND_THEMES.md`](./HOWTO_REGISTER_COMPONENTS_AND_THEMES.md) und [`docs/tutorials/NEW_COMPONENT.md`](./tutorials/NEW_COMPONENT.md).\n- Skeleton-Architektur: [`packages/components/src/components/_skeleton/ARC42.md`](../packages/components/src/components/_skeleton/ARC42.md), `.claude/skills/migrate-to-skeleton/SKILL.md`, `.github/agents/migrate-to-skeleton.agent.md`.\n- Skills und Companion-Pläne: `.claude/skills/theme-redundancy-check/SKILL.md`, `.claude/skills/zero-visual-delta-handoff/SKILL.md`.\n\n## 9. Nicht-Ziele und Folgearbeiten\n\n- Dieses Konzept implementiert kein Dark Theme. Es legt nur fest, wo eine Umsetzung stattfindet.\n- Die bestehenden Schwarz/Weiß-Fallbacks in der Basis bleiben unverändert.\n- Folgearbeit: eine Stylelint-Regel `kolibri/component-no-color-scheme` im Paket `packages/tools/stylelint-rules`, die `prefers-color-scheme`, `color-scheme` und `light-dark()` in `packages/components` verbietet und damit die Regel aus [Abschnitt 4.1](#41-komponenten-paket-packagescomponents) maschinell absichert.\n- Folgearbeit: ein `dark`-Lauf des `unstyled`-Snapshot-Checks in der CI als dauerhafter Nachweis der Scheme-Neutralität.\n",
277
+ "code": "# Basis-Styling vs. Theming Konzept\n\nBeschreibt die Abgrenzung zwischen dem Basis-Styling der Komponenten (`@public-ui/components`) und dem Theming in den Theme-Paketen (`@public-ui/theme-*`) – mit dem klaren Grundsatz, dass Dark/Light-Color-Schemes ausschließlich im Theme verankert werden.\n\n## Status\n\n- Ist: Das Basis-Styling in `packages/components/src` ist scheme-frei – dort gibt es weder `prefers-color-scheme` noch `color-scheme` oder `light-dark()`. `@public-ui/theme-default` implementiert seit [#10831](https://github.com/public-ui/kolibri/pull/10831) ein Dark Color Scheme über `light-dark()` und `color-scheme.css`; alle übrigen Themes liefern bisher nur eine helle Palette.\n- Soll: Die Abgrenzung ist verbindlich festgeschrieben und in allen Konzepten, Agenten-Anweisungen und Skills verankert (siehe [Abschnitt 8](#8-verankerung-in-den-bestehenden-konzepten)). Zukünftige Dark/Light-Umsetzungen entstehen ausschließlich in den Theme-Paketen.\n\n## 1. Leitsatz\n\n> **Das Basis-Styling in `@public-ui/components` (Layer `kol-a11y`, `kol-global`, `kol-component`) ist ausschließlich für Layout und Struktur zuständig. Es kennt kein Dark/Light-Color-Scheme: kein `prefers-color-scheme`, kein `color-scheme`, kein `light-dark()`, keine Scheme-Tokens und keine Scheme-Modifier. Schwarz und Weiß in der Basis sind ein Kontrast-Fallback, keine Farbgestaltung. Dark/Light-Theming wird ausschließlich in den Theme-Paketen (Layer `kol-theme-global`, `kol-theme-component`) verankert und umgesetzt.**\n\nDer Fokus der Basis liegt auf dem Layout. Der Fokus der Themes liegt auf der Optik – dazu gehören alle Farbkombinationen, also auch die Entscheidung für ein helles oder dunkles Erscheinungsbild.\n\n## 2. Ziel\n\n- Komponenten funktionieren strukturell in jedem Theme identisch. Ein Theme-Wechsel ändert nie das Layout.\n- Themes tragen die vollständige visuelle Verantwortung. Ein Theme kann hell, dunkel oder beides anbieten, ohne dass das Komponenten-Paket angefasst werden muss.\n- Die Basis bleibt scheme-neutral. Das `unstyled`-Theme (`packages/unstyled/theme.ts`) rendert nur den Basis-Layer und muss unter der Browser-Einstellung `light` und `dark` identisch aussehen.\n- Es gibt genau eine Stelle, an der Farbentscheidungen getroffen werden. Das vermeidet Konflikte zwischen Basis-Farben und Theme-Farben und hält die Kontrastprüfung (WCAG) beim Theme.\n\n## 3. Verantwortlichkeiten je Schicht\n\nDie Layer-Reihenfolge ist in `packages/components/src/components/_layer-order.scss` definiert:\n\n```scss\n@layer kol-a11y, kol-global, kol-component, kol-theme-global, kol-theme-component, kol-forced-colors, kol-theme-forced-colors;\n```\n\n| Layer | Paket | Zuständig für | Ausdrücklich nicht zuständig für |\n| ------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |\n| `kol-a11y` | `@public-ui/components` | Barrierefreiheits-Baseline: Mindestgrößen, Schriftvererbung, Schwarz/Weiß als Kontrast-Fallback | Farbgestaltung, Color Schemes |\n| `kol-global` | `@public-ui/components` | Globale Layout-Defaults: `box-sizing`, Basis-`font-size`, Resets | Farben, Abstände (`margin`, `padding`, `gap`), Color Schemes |\n| `kol-component` | `@public-ui/components` | Komponenten-Layout: Display, Flex/Grid, Position, Dimensionen, strukturelle Typografie | Farben (außer Schwarz/Weiß-Fallback), Abstände, Schatten, Rahmen-Optik, Color Schemes |\n| `kol-theme-global` | `@public-ui/theme-*` | Design-Tokens (Farben, Schriften, Abstände, Radien), **Color Schemes (Light/Dark)**, Fokus-Optik | Layout-Regeln, die bereits in der Basis stehen |\n| `kol-theme-component` | `@public-ui/theme-*` | Komponentenspezifische Optik: Farben, Rahmen, Schatten, Abstände über Tokens | Layout-Regeln der Basis, eigene Scheme-Media-Queries pro Komponente |\n| `kol-forced-colors` | `@public-ui/components` | Barrierefreiheit unter `forced-colors: active` mit System-Farbschlüsselwörtern | Dark Mode (siehe [Abschnitt 5](#5-abgrenzung-forced-colors-ist-kein-dark-mode)) |\n| `kol-theme-forced-colors` | `@public-ui/theme-*` | Theme-spezifische Ergänzungen für Forced Colors | Dark Mode |\n\nDie Verbotsliste für das Komponenten-Paket steht in [`CODE_STYLE_AND_CONVENTIONS.md`](./CODE_STYLE_AND_CONVENTIONS.md). Die fünf Styling-Schichten sind in [`AGENTS.md`](../AGENTS.md#theming) und in der arc42-Dokumentation ([ADR-008](./arc42/09-architecture-decisions.md#adr-008-five-layer-styling-architecture)) beschrieben.\n\n## 4. Dark/Light: Regeln\n\n### 4.1 Komponenten-Paket (`packages/components`)\n\nIn den Basis-Layern sind verboten:\n\n- `@media (prefers-color-scheme: …)` in jeder Form\n- die CSS-Eigenschaft `color-scheme`\n- die CSS-Funktion `light-dark()`\n- Custom Properties, deren Wert vom Scheme abhängt (z. B. `--kol-…-dark`)\n- Scheme-Modifier im Markup oder in BEM-Klassen (z. B. `kol-button--dark`)\n- Props oder States, die ein Color Scheme transportieren\n\nBegründung:\n\n1. Die Basis hat den Fokus auf Layout. Jede Farbentscheidung wäre eine Design-Entscheidung, die nur das Theme treffen darf.\n2. Ein Scheme in der Basis würde mit den Farben jedes Themes kollidieren und die Kontrastprüfung vom Theme zurück in die Basis verlagern.\n3. Das `unstyled`-Theme muss als scheme-neutrale Baseline unter `light` und `dark` identische Snapshots liefern. Nur so bleibt es ein verlässlicher Indikator für DOM-Umbauten (siehe `.claude/skills/zero-visual-delta-handoff/SKILL.md`, Fallstricke).\n\nErlaubt bleibt der Kontrast-Fallback aus dem A11y-Preset: `background-color: white; color: black`. Diese Werte sind keine Farbgestaltung, sondern erzwingen ein geprüftes Kontrastverhältnis, bis ein Theme die Farben setzt. Bestehende `white`/`black`-Stellen in der Basis (z. B. `@shared/_table-stateless.mixin.scss`, `input-checkbox/style.scss`) sind Fallbacks in diesem Sinn und werden nicht in Scheme-Logik überführt.\n\n### 4.2 Theme-Pakete (`packages/themes/*`)\n\nDark/Light wird vollständig im Theme umgesetzt. Empfohlenes Muster:\n\n1. **Tokens im globalen Theme-Layer auf `:host`** – wie heute in `packages/themes/default/src/global.scss`. Alle Farben, die sich zwischen Light und Dark unterscheiden, sind Tokens (`--color-…`), niemals Literale in Komponenten-Styles.\n2. **Scheme-Umschaltung an einer Stelle** – ebenfalls im Layer `kol-theme-global`:\n - automatisch per `color-scheme: light dark` und `light-dark()` in den Token-Werten, oder\n - per `@media (prefers-color-scheme: dark)` mit überschriebenen Tokens, oder\n - per Opt-in über ein Attribut oder eine Klasse am Host, wenn Anwendungen das Scheme selbst steuern sollen.\n3. **Komponenten-Theme-Layer referenziert nur Tokens.** Keine Scheme-Media-Queries pro Komponente. Ändert sich das Scheme, ändern sich nur die Token-Werte.\n4. **Alternative: eigener Theme-Export.** Ein Theme kann zusätzlich einen dunklen Export (z. B. `DEFAULT_DARK`) bereitstellen, der über `register([DEFAULT, DEFAULT_DARK], …)` registriert und zur Laufzeit über das Attribut `kol-theme` umgeschaltet wird (siehe [`HOWTO_REGISTER_COMPONENTS_AND_THEMES.md`](./HOWTO_REGISTER_COMPONENTS_AND_THEMES.md) und arc42 [§6.4 Theme Switching](./arc42/06-runtime-view.md#64-theme-switching)).\n\nBeispiel für Variante 2a im globalen Theme-Layer:\n\n```scss\n@layer kol-theme-global {\n\t:host {\n\t\tcolor-scheme: light dark;\n\t\t--color-text: var(--kolibri-color-text, light-dark(#202020, #f2f3f4));\n\t\t--color-light: var(--kolibri-color-light, light-dark(#ffffff, #1a1a1a));\n\t}\n}\n```\n\nKontrastanforderungen (mindestens 4,5:1 für Text, 3:1 für UI-Komponenten, siehe arc42 [Kapitel 8](./arc42/08-cross-cutting-concepts.md)) gelten für jedes Scheme einzeln und werden vom Theme nachgewiesen.\n\n## 5. Abgrenzung: Forced Colors ist kein Dark Mode\n\n`packages/components/src/components/forced-colors.scss` (Layer `kol-forced-colors`) reagiert auf `@media (forced-colors: active)` und verwendet System-Farbschlüsselwörter wie `Canvas`, `CanvasText`, `ButtonText` oder `Highlight`. Das ist ein Barrierefreiheitsmechanismus für Hochkontrast-Modi des Betriebssystems, keine Gestaltung: Das System liefert die Farben, die Basis stellt nur sicher, dass Struktur und Zustände sichtbar bleiben.\n\nDeshalb bleibt Forced Colors in der Basis erlaubt, während Dark/Light-Schemes ausgeschlossen sind. Die beiden Mechanismen dürfen nicht vermischt werden: `forced-colors` ist kein Ersatz für `prefers-color-scheme` und umgekehrt.\n\n## 6. Entscheidungsregel für Regelverschiebungen\n\nDer Skill `theme-redundancy-check` verschiebt redundante Regeln aus Themes in die Basis. Zusätzlich zur bestehenden Frage „Würde sich die Regel beim Wechsel eines Themes visuell ändern?“ gilt:\n\n> **Würde sich der Wert beim Wechsel Light ↔ Dark ändern?** Ja → die Regel bleibt im Theme. Nein → Kandidat für die Basis.\n\nJede Farbe ist damit automatisch Theme-Sache. Layout-Regeln, die in beiden Schemes gleich sind, sind Basis-Kandidaten.\n\n## 7. Nachweis und Tests\n\n- `packages/unstyled` ist die scheme-neutrale Baseline. Der visuelle Test-Harness unterstützt `KOLIBRI_VISUAL_TESTS_COLOR_SCHEME=light|dark` (`packages/tools/visual-tests/playwright.config.js`). Ein Lauf des `unstyled`-Checks unter `dark` muss gegen die `light`-Baselines 0 Diffs liefern. Das ist der Beweis, dass die Basis kein Scheme kennt.\n- Für Themes, die Dark/Light anbieten, werden Snapshots pro Scheme geführt. Das Layout muss zwischen beiden Snapshot-Sätzen pixelgleich bleiben; nur Farben dürfen sich unterscheiden.\n- Stichprobe für das Komponenten-Paket: eine Suche nach `prefers-color-scheme`, `color-scheme` und `light-dark(` in `packages/components/src` muss leer bleiben.\n\n## 8. Verankerung in den bestehenden Konzepten\n\nDer Leitsatz aus [Abschnitt 1](#1-leitsatz) ist an folgenden Stellen eingearbeitet:\n\n- [`AGENTS.md`](../AGENTS.md#theming): Styling-Schichten, Custom-Theming-Regeln und allgemeine Theme-Regeln.\n- [`docs/CODE_STYLE_AND_CONVENTIONS.md`](./CODE_STYLE_AND_CONVENTIONS.md): Verbotsliste für das Komponenten-Paket, Zuständigkeit der Themes.\n- [`packages/components/AGENTS.md`](../packages/components/AGENTS.md) und [`packages/components/src/components/README.md`](../packages/components/src/components/README.md): Styling-Grenze für Komponenten.\n- [`packages/themes/AGENTS.md`](../packages/themes/AGENTS.md): Dark/Light als Theme-Verantwortung.\n- arc42 (EN und DE): [Lösungsstrategie](./arc42/04-solution-strategy.md), [Bausteinsicht](./arc42/05-building-block-view.md), [Architekturentscheidungen](./arc42/09-architecture-decisions.md) (ADR-008, ADR-018), [Qualitätsanforderungen](./arc42/10-quality-requirements.md) (Szenario P3), [Glossar](./arc42/12-glossary.md).\n- [`docs/HOWTO_REGISTER_COMPONENTS_AND_THEMES.md`](./HOWTO_REGISTER_COMPONENTS_AND_THEMES.md) und [`docs/tutorials/NEW_COMPONENT.md`](./tutorials/NEW_COMPONENT.md).\n- Skeleton-Architektur: [`packages/components/docs/ARC42-SKELETON.md`](../packages/components/docs/ARC42-SKELETON.md), `.claude/skills/migrate-to-skeleton/SKILL.md`, `.github/agents/migrate-to-skeleton.agent.md`.\n- Skills und Companion-Pläne: `.claude/skills/theme-redundancy-check/SKILL.md`, `.claude/skills/zero-visual-delta-handoff/SKILL.md`.\n\n## 9. Nicht-Ziele und Folgearbeiten\n\n- Dieses Konzept implementiert kein Dark Theme. Es legt nur fest, wo eine Umsetzung stattfindet.\n- Die bestehenden Schwarz/Weiß-Fallbacks in der Basis bleiben unverändert.\n- Folgearbeit: eine Stylelint-Regel `kolibri/component-no-color-scheme` im Paket `packages/tools/stylelint-rules`, die `prefers-color-scheme`, `color-scheme` und `light-dark()` in `packages/components` verbietet und damit die Regel aus [Abschnitt 4.1](#41-komponenten-paket-packagescomponents) maschinell absichert.\n- Folgearbeit: ein `dark`-Lauf des `unstyled`-Snapshot-Checks in der CI als dauerhafter Nachweis der Scheme-Neutralität.\n",
278
278
  "kind": "doc"
279
279
  },
280
280
  {
@@ -310,7 +310,7 @@
310
310
  "name": "BREAKING_CHANGES.v5",
311
311
  "description": "New major versions of KoliBri are developed with the goal of simplifying maintenance and support and promoting further development.",
312
312
  "path": "docs/BREAKING_CHANGES.v5.md",
313
- "code": "# Breaking Changes for version 5\n\n## Introduction\n\nNew major versions of KoliBri are developed with the goal of simplifying maintenance and support and promoting further development.\n\nFor more information, see the [KoliBri Maintenance and Support Strategy](https://github.com/public-ui/kolibri/blob/develop/MIGRATION.md).\n\n## Removal of the `@public-ui/themes` meta package\n\nThe `@public-ui/themes` meta package only ever re-exported and bundled the individual theme packages.\nIt was never meant to be used directly and is the reason for a circular dependency between the themes,\nthe visual-tests runner and the sample app.\n\nStarting with version 4 the package is **deprecated**; it will be **removed in version 5**. Migrate to\nthe individual `@public-ui/theme-*` packages instead. When an application uses several themes (as the\npresentation app does), add every theme as its own dependency.\n\n### Package dependency\n\nReplace the meta package with the individual theme packages you actually use:\n\n**Before (v4):**\n\n```jsonc\n{\n\t\"dependencies\": {\n\t\t\"@public-ui/themes\": \"^4.0.0\",\n\t},\n}\n```\n\n**After:**\n\n```jsonc\n{\n\t\"dependencies\": {\n\t\t\"@public-ui/theme-default\": \"^4.0.0\",\n\t\t\"@public-ui/theme-ecl\": \"^4.0.0\",\n\t},\n}\n```\n\n| Meta export | Individual package |\n| ----------- | -------------------------- |\n| `DEFAULT` | `@public-ui/theme-default` |\n| `BWSt` | `@public-ui/theme-bwst` |\n| `DesyV11` | `@public-ui/theme-desy` |\n| `ECL_EC` | `@public-ui/theme-ecl` |\n| `ECL_EU` | `@public-ui/theme-ecl` |\n| `KERN_V2` | `@public-ui/theme-kern` |\n\n### Imports\n\n**Before (v4):**\n\n```ts\nimport { BWSt, DEFAULT, DesyV11, ECL_EC, ECL_EU, KERN_V2 } from '@public-ui/themes';\n```\n\n**After:**\n\n```ts\nimport { BWSt } from '@public-ui/theme-bwst';\nimport { DEFAULT } from '@public-ui/theme-default';\nimport { DesyV11 } from '@public-ui/theme-desy';\nimport { ECL_EC, ECL_EU } from '@public-ui/theme-ecl';\nimport { KERN_V2 } from '@public-ui/theme-kern';\n```\n\n### Assets\n\nThe meta package aggregated the assets (fonts, icons) of all themes into a single `assets` folder.\nWithout it, copy the assets from each individual theme package you use.\n\n**Before (v4):**\n\n```jsonc\n{\n\t\"scripts\": {\n\t\t\"prebuild:themes\": \"cpy \\\"node_modules/@public-ui/themes/assets/**/*\\\" public/assets --dot\",\n\t},\n}\n```\n\n**After:**\n\n```jsonc\n{\n\t\"scripts\": {\n\t\t\"prebuild:theme-default\": \"cpy \\\"node_modules/@public-ui/theme-default/assets/**/*\\\" public/assets --dot\",\n\t\t\"prebuild:theme-ecl\": \"cpy \\\"node_modules/@public-ui/theme-ecl/assets/**/*\\\" public/assets --dot\",\n\t},\n}\n```\n\n## Removal of legacy schema types of skeleton-migrated components\n\nComponents migrated to the skeleton architecture no longer carry a mutable `state` bag, so the\n`*States` and `*API` types of the legacy `Generic.Element.ComponentApi` shape describe nothing\nanymore. They were still re-exported from `@public-ui/components` (via `schema/components`) and are\n**removed**:\n\n| Component | Removed types |\n| ------------------ | --------------------------------------------------------------------------- |\n| `kol-abbr` | `AbbrProps`, `AbbrStates`, `AbbrAPI` |\n| `kol-avatar` | `AvatarProps`, `AvatarStates`, `AvatarAPI` |\n| `kol-button` | `ButtonStates`, `ButtonAPI`, `RequiredButtonStates`, `OptionalButtonStates` |\n| `kol-button-link` | `ButtonLinkStates` |\n| `kol-icon` | `IconProps`, `IconStates`, `IconWatches`, `IconAPI`, `InternalIconProps` |\n| `kol-link` | `LinkStates`, `LinkAPI`, `InternalLinkAPI` |\n| `kol-progress` | `ProgressProps`, `ProgressStates`, `ProgressAPI` |\n| `kol-quote` | `QuoteProps`, `QuoteStates`, `QuoteAPI` |\n| `kol-span` | `SpanProps`, `SpanStates`, `SpanAPI` |\n| `kol-spin` | `SpinProps`, `SpinStates`, `SpinAPI` |\n| `kol-split-button` | `SplitButtonStates`, `SplitButtonAPI` |\n| `kol-tooltip` | `TooltipProps`, `TooltipStates`, `TooltipAPI` |\n\nThe `*Props` types of components that still have consumers (`ButtonProps`, `InternalButtonProps`,\n`LinkProps`, `ButtonLinkProps`, `LinkButtonProps`, `SplitButtonProps`, …) stay. Type the public\nprops of a migrated element through the element itself, e.g. `Pick<HTMLKolAbbrElement, '_label'>`,\nor through the internal prop definitions in `src/internal/props`.\n",
313
+ "code": "# Breaking Changes for version 5\n\n## Introduction\n\nNew major versions of KoliBri are developed with the goal of simplifying maintenance and support and promoting further development.\n\nFor more information, see the [KoliBri Maintenance and Support Strategy](https://github.com/public-ui/kolibri/blob/develop/MIGRATION.md).\n\n## Removal of the `@public-ui/themes` meta package\n\nThe `@public-ui/themes` meta package only ever re-exported and bundled the individual theme packages.\nIt was never meant to be used directly and is the reason for a circular dependency between the themes,\nthe visual-tests runner and the sample app.\n\nStarting with version 4 the package is **deprecated**; it will be **removed in version 5**. Migrate to\nthe individual `@public-ui/theme-*` packages instead. When an application uses several themes (as the\npresentation app does), add every theme as its own dependency.\n\n### Package dependency\n\nReplace the meta package with the individual theme packages you actually use:\n\n**Before (v4):**\n\n```jsonc\n{\n\t\"dependencies\": {\n\t\t\"@public-ui/themes\": \"^4.0.0\",\n\t},\n}\n```\n\n**After:**\n\n```jsonc\n{\n\t\"dependencies\": {\n\t\t\"@public-ui/theme-default\": \"^4.0.0\",\n\t\t\"@public-ui/theme-ecl\": \"^4.0.0\",\n\t},\n}\n```\n\n| Meta export | Individual package |\n| ----------- | -------------------------- |\n| `DEFAULT` | `@public-ui/theme-default` |\n| `BWSt` | `@public-ui/theme-bwst` |\n| `DesyV11` | `@public-ui/theme-desy` |\n| `ECL_EC` | `@public-ui/theme-ecl` |\n| `ECL_EU` | `@public-ui/theme-ecl` |\n| `KERN_V2` | `@public-ui/theme-kern` |\n\n### Imports\n\n**Before (v4):**\n\n```ts\nimport { BWSt, DEFAULT, DesyV11, ECL_EC, ECL_EU, KERN_V2 } from '@public-ui/themes';\n```\n\n**After:**\n\n```ts\nimport { BWSt } from '@public-ui/theme-bwst';\nimport { DEFAULT } from '@public-ui/theme-default';\nimport { DesyV11 } from '@public-ui/theme-desy';\nimport { ECL_EC, ECL_EU } from '@public-ui/theme-ecl';\nimport { KERN_V2 } from '@public-ui/theme-kern';\n```\n\n### Assets\n\nThe meta package aggregated the assets (fonts, icons) of all themes into a single `assets` folder.\nWithout it, copy the assets from each individual theme package you use.\n\n**Before (v4):**\n\n```jsonc\n{\n\t\"scripts\": {\n\t\t\"prebuild:themes\": \"cpy \\\"node_modules/@public-ui/themes/assets/**/*\\\" public/assets --dot\",\n\t},\n}\n```\n\n**After:**\n\n```jsonc\n{\n\t\"scripts\": {\n\t\t\"prebuild:theme-default\": \"cpy \\\"node_modules/@public-ui/theme-default/assets/**/*\\\" public/assets --dot\",\n\t\t\"prebuild:theme-ecl\": \"cpy \\\"node_modules/@public-ui/theme-ecl/assets/**/*\\\" public/assets --dot\",\n\t},\n}\n```\n\n## Removal of legacy schema types of skeleton-migrated components\n\nComponents migrated to the skeleton architecture no longer carry a mutable `state` bag, so the\n`*States` and `*API` types of the legacy `Generic.Element.ComponentApi` shape describe nothing\nanymore. They were still re-exported from `@public-ui/components` (via `schema/components`) and are\n**removed**:\n\n| Component | Removed types |\n| ------------------ | --------------------------------------------------------------------------- |\n| `kol-abbr` | `AbbrProps`, `AbbrStates`, `AbbrAPI` |\n| `kol-avatar` | `AvatarProps`, `AvatarStates`, `AvatarAPI` |\n| `kol-button` | `ButtonStates`, `ButtonAPI`, `RequiredButtonStates`, `OptionalButtonStates` |\n| `kol-button-link` | `ButtonLinkStates` |\n| `kol-icon` | `IconProps`, `IconStates`, `IconWatches`, `IconAPI`, `InternalIconProps` |\n| `kol-link` | `LinkStates`, `LinkAPI`, `InternalLinkAPI` |\n| `kol-progress` | `ProgressProps`, `ProgressStates`, `ProgressAPI` |\n| `kol-quote` | `QuoteProps`, `QuoteStates`, `QuoteAPI` |\n| `kol-span` | `SpanProps`, `SpanStates`, `SpanAPI` |\n| `kol-spin` | `SpinProps`, `SpinStates`, `SpinAPI` |\n| `kol-split-button` | `SplitButtonStates`, `SplitButtonAPI` |\n| `kol-tooltip` | `TooltipProps`, `TooltipStates`, `TooltipAPI` |\n\nThe `*Props` types of components that still have consumers (`ButtonProps`, `InternalButtonProps`,\n`LinkProps`, `ButtonLinkProps`, `LinkButtonProps`, `SplitButtonProps`, …) stay. Type the public\nprops of a migrated element through the element itself, e.g. `Pick<HTMLKolAbbrElement, '_label'>`,\nor through the internal prop definitions in `src/internal/props`.\n\n## Removal of the deprecated `kol-tooltip-wc` element\n\nThe `kol-tooltip-wc` element was the last remaining web component without Shadow DOM. It rendered the\ninternal tooltip of KoliBri components into the light DOM and was kept deprecated for a single\nintegrator only. It is removed together with the `KolTooltipWc` export, the `KolTooltipWcTag`\nconstant and the generated `HTMLKolTooltipWcElement` types.\n\nTooltips that KoliBri components render themselves (for example hints next to labels or buttons) keep\nworking unchanged. They are rendered by the components internally and never required the standalone\nelement.\n\nThere is no standalone replacement. If your application rendered `<kol-tooltip-wc>` on its own,\nmigrate to an application-provided tooltip, such as the native `title` attribute or a self-built\npopover. The `@public-ui/kolibri-cli` migration tool removes remaining usages and imports\nautomatically (`npx @public-ui/kolibri-cli migrate src`).\n\n**Before (v4):**\n\n```tsx\nimport { KolTooltipWc } from '@public-ui/components';\n\n<KolTooltipWc _align=\"top\" _id=\"my-tooltip\" _label=\"Tooltip text\" />;\n```\n\n**After (v5):**\n\n```tsx\n// The element and its exports no longer exist. Remove the usage; tooltips of\n// KoliBri components keep working without it.\n```\n",
314
314
  "kind": "doc"
315
315
  },
316
316
  {
@@ -328,7 +328,7 @@
328
328
  "name": "CLICK_EVENT_BUBBLE_CONCEPT",
329
329
  "description": "Beschreibt, wie Click-Events durch die KoliBri-Komponentenschichten propagiert werden: HTML5-Element im Shadow DOM → Host-Element (als Custom Event).",
330
330
  "path": "docs/CLICK_EVENT_BUBBLE_CONCEPT.md",
331
- "code": "# Click Event Bubble/Emission Concept\n\nBeschreibt, wie Click-Events durch die KoliBri-Komponentenschichten propagiert werden: HTML5-Element im Shadow DOM → Host-Element (als Custom Event).\n\n## Überblick\n\nKoliBri Web Components verwenden Shadow DOM für Style-Isolation. Native Click-Events von Elementen innerhalb eines Shadow DOM geben zwar durch `composed: true` den Shadow-Grenzwert durch, berichten jedoch den Shadow Host als `event.target` – das eigentliche innere Element ist außen nicht sichtbar. Außerdem würde bei mehrfach verschachtelten Komponenten ein unkontrolliertes Durchsickern von Click-Events zu unerwünschtem Verhalten führen.\n\nKoliBri löst dieses Problem mit einem kontrollierten Zwei-Kanal-System:\n\n1. **Callback-Kanal** (`_on.onClick`) – direkter JavaScript-Callback, erhält das korrigierte Event-Target\n2. **DOM-Event-Kanal** – ein `CustomEvent` mit `composed: true` wird vom Host-Element neu ausgelöst\n\n## Architektur\n\n### Der Zwei-Kanal-Ansatz\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ Äußeres Konsumenten-Element │\n│ │\n│ element.addEventListener('click', handler) (2) │\n│ OR: _on={{ onClick: handler }} (1) │\n└──────────────────────────────┬───────────────────────────────────┘\n CustomEvent│ bubbles, composed (2)\n │ dispatchDomEvent(host, KolEvent.click)\n┌──────────────────────────────┴───────────────────────────────────┐\n│ Shadow Component: kol-button / kol-link (shadow: true) │\n│ Handler aus BaseButtonWebComponent / BaseLinkWebComponent │\n│ │\n│ handleClick(event) { │\n│ event.stopPropagation() ← native click abfangen │\n│ setEventTarget(event, ctaRef.el) ← Target korrigieren (1) │\n│ _on?.onClick(event, value) ← Callback aufrufen (1) │\n│ dispatchDomEvent(host, KolEvent.click, value) ← Event (2) │\n│ } │\n└──────────────────────────────┬───────────────────────────────────┘\n native │ click (stopPropagation verhindert Austritt)\n MouseEvent │\n┌──────────────────────────────┴───────────────────────────────────┐\n│ HTML5 Element: <button> / <a> (Functional Component) │\n│ Ursprung des nativen Click-Events │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### Warum `event.stopPropagation()` bei Buttons?\n\nNative Click-Events haben `composed: true` und passieren die Shadow-DOM-Grenze; außen erscheint dann der Host als `event.target`. Das Durchsickern des nativen Events nach außen würde:\n\n- neben dem Custom Event ein zweites `click` am Host auslösen\n- die Callback-/DOM-Event-Dualität untergraben, da Konsumenten beide Signale erhalten würden\n\nDeshalb wird die native Propagation mit `stopPropagation()` unterbrochen und ein kontrolliertes\nCustom Event vom Host-Element neu ausgelöst.\n\n> **Hinweis zu Links:** Der Link-Handler ruft kein `stopPropagation()` auf. Die native Navigation\n> des `<a>`-Elements wird bei `_disabled: true` über `event.preventDefault()` unterbunden; in diesem\n> Fall entfallen Callback und Custom Event.\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Sortier-Buttons von `kol-table-stateless` oder die Buttons von `kol-pagination`), rendert sie deren Functional Component über ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/src/components/_skeleton/ARC42.md#embedded-components-items)). Das Item übernimmt dieselben Schritte wie der Handler oben, dispatcht das Custom Event aber auf dem Wurzelknoten der Functional Component (`.kol-button`, `.kol-link`). Von dort bubblet es mit `composed: true` durch den Shadow DOM der einbettenden Komponente und über deren Host nach außen.\n\n## Utility-Funktionen und Typen\n\n### `dispatchDomEvent(target, event, detail)` — `packages/components/src/utils/events.ts`\n\nErstellt ein `CustomEvent` und dispatcht es vom Ziel-Element.\n\n```typescript\nfunction dispatchDomEvent<T>(target: HTMLElement, event: KolEvent, detail?: T) {\n\ttarget.dispatchEvent(createKoliBriEvent<T>(event, detail));\n}\n```\n\nDas zugrundeliegende Event wird mit diesen Optionen erstellt:\n\n```typescript\nconst DEFAULT_OPTIONS = {\n\tbubbles: true,\n\tcancelable: true,\n\tcomposed: true,\n} as const;\n```\n\n- **`bubbles: true`** — Das Event steigt im DOM nach oben\n- **`composed: true`** — Das Event kann Shadow-DOM-Grenzen passieren\n- **`cancelable: true`** — Das Event kann mit `preventDefault()` abgebrochen werden\n- **`detail`** — Trägt den Komponentenwert (z. B. `_value` bei Buttons, `_href` bei Links)\n\n### `KolEvent` — `packages/components/src/utils/events.ts`\n\nEnum aller Event-Namen, die KoliBri dispatcht:\n\n```typescript\nenum KolEvent {\n\tblur = 'blur',\n\tchange = 'change',\n\tclick = 'click',\n\tfocus = 'focus',\n\tinput = 'input',\n\t// ...weitere Events\n}\n```\n\nDer Event-Name `KolEvent.click` entspricht dem String `\"click\"`.\n\n### `setEventTarget(event, element)` — `packages/components/src/schema`\n\nKorrigiert das `target` eines Events auf das angegebene Element. Wird vor dem Callback-Aufruf\nverwendet, damit der Konsument das innere HTML5-Element (z. B. `<button>`, `<a>`) als Target erhält.\n\n### Callback-Typen — `packages/components/src/schema/types/callbacks.ts`\n\n```typescript\nexport type EventCallback<E extends Event> = (event: E) => void;\nexport type EventValueOrEventCallback<E extends Event, V> = ((event: E, value: V) => void) | EventCallback<E>;\n```\n\n- `EventCallback<E>` — einfacher Event-Handler ohne Wert\n- `EventValueOrEventCallback<E, V>` — Handler mit optionalem Komponentenwert als zweitem Argument\n\n## Umsetzung in Komponenten\n\n### Interaktive Elemente (Button, Link)\n\nDie Handler liegen in den gemeinsamen Basisklassen und werden der Functional Component als `handleClick` bzw. `handleAnchorClick` übergeben.\n\n#### Button — `BaseButtonWebComponent` (`packages/components/src/components/button/base.tsx`)\n\n```typescript\nprotected readonly handleClick = (event: MouseEvent): void => {\n\tevent.stopPropagation(); // Natives Event abfangen\n\tthis.tooltipBehavior.hideTooltip();\n\n\tconst type = this.getRenderProp('type');\n\tif (type === 'submit') {\n\t\tpropagateSubmitEventToForm({ form: this.host, ref: this.ctaRef.el });\n\t} else if (type === 'reset') {\n\t\tpropagateResetEventToForm({ form: this.host, ref: this.ctaRef.el });\n\t} else {\n\t\tthis.formAssociation.setFormAssociatedValue(this.formValue);\n\n\t\tconst onClick = this.getRenderProp('on').onClick;\n\t\tif (typeof onClick === 'function') {\n\t\t\tsetEventTarget(event, this.ctaRef.el); // Target korrigieren\n\t\t\tonClick(event, this.formValue); // (1) Callback\n\t\t}\n\t}\n\n\tif (this.host) {\n\t\tdispatchDomEvent(this.host, KolEvent.click, this.formValue); // (2) DOM-Event\n\t}\n};\n```\n\n#### Link — `BaseLinkWebComponent` (`packages/components/src/components/link/base.tsx`)\n\n```typescript\nprotected readonly handleAnchorClick = (event: Event): void => {\n\tthis.tooltipBehavior.hideTooltip();\n\tif (this.getRenderProp('disabled') === true) {\n\t\tevent.preventDefault(); // Navigation verhindern\n\t\treturn;\n\t}\n\tconst href = this.getRenderProp('href');\n\tconst on = this.getRenderProp('on');\n\tif (typeof on?.onClick === 'function') {\n\t\tsetEventTarget(event, this.ctaRef.el); // Target korrigieren\n\t\ton.onClick(event, href); // (1) Callback\n\t}\n\tif (this.host) {\n\t\tdispatchDomEvent(this.host, KolEvent.click, href); // (2) DOM-Event\n\t}\n};\n```\n\nDie Tastaturbedienung braucht keinen eigenen Handler: Enter auf einem `<a href>` und Enter/Space auf einem `<button>` lösen nativ ein `click` aus.\n\n### Input-Elemente\n\nInput-Elemente (z. B. `kol-input-text`, `kol-input-checkbox`) leiten Click-Events ebenfalls\nüber den `_on`-Prop-Mechanismus weiter. Der `InputTypeOnClick`-Typ ist Teil des Standard-Event-Sets:\n\n```typescript\n// packages/components/src/schema/types/input/types.ts\ntype InputTypeOnClick = {\n\t[Callback.onClick]?: EventCallback<Event>;\n};\n\nexport type InputTypeOnDefault = InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown;\n```\n\nDas Muster für Input-Komponenten ist analog zu Buttons: `onClick` im `_on`-Objekt + `dispatchDomEvent`.\n\n## Konsumenten-Perspektive\n\n```typescript\n// (1) Callback-Kanal — typsicher, erhält den Komponentenwert:\n<KolButton _label=\"Senden\" _on={{ onClick: (event, value) => console.log(value) }} />\n\n// (2) DOM-Event-Kanal — Standard-Web-API, z. B. für Framework-Integration:\ndocument.querySelector('kol-button').addEventListener('click', (event: CustomEvent) => {\n\tconst value = event.detail; // Komponentenwert aus event.detail\n});\n```\n\n### Vergleich der beiden Kanäle\n\n| Eigenschaft | Callback (`_on.onClick`) | DOM CustomEvent (`addEventListener`) |\n| --------------- | --------------------------------------------- | ----------------------------------------------- |\n| API | KoliBri-spezifisch | Standard Web API |\n| Event-Target | Korrigiert auf inneres HTML5-Element | Host-Element (`kol-button`, `kol-link`, etc.) |\n| Komponentenwert | Als zweites Argument `value` | In `event.detail` |\n| Typ | `EventValueOrEventCallback<MouseEvent, V>` | `CustomEvent<V>` |\n| Bubbles | Nein (direkter Funktionsaufruf) | Ja (`bubbles: true, composed: true`) |\n| Geeignet für | Direkte Framework-Integration (React, Vue...) | Vanilla JS, Event-Delegation, Framework-Adapter |\n\n## Zusammenfassung\n\n| Schritt | Was passiert |\n| ------- | ---------------------------------------------------------------------------- |\n| 1 | Nutzer klickt → nativer `MouseEvent` auf `<button>` / `<a>` |\n| 2 | Handler fängt Event ab, ruft `event.stopPropagation()` (nur Button) |\n| 3 | `setEventTarget(event, ctaRef.el)` korrigiert das Event-Target |\n| 4 | `_on?.onClick(event, value)` — Callback-Kanal wird bedient |\n| 5 | `dispatchDomEvent(host, KolEvent.click, value)` — neues Custom Event am Host |\n| 6 | Das Custom Event bubblet mit `composed: true` durch den DOM-Baum |\n\n**Wichtig:**\n\n- Das native Click-Event eines Buttons verlässt die Komponente **nicht** unkontrolliert\n- Das Custom Event trägt stets den **Komponentenwert** in `event.detail` (kein DOM-Wert)\n- `setEventTarget` stellt sicher, dass der Callback das **innere Element** als Target erhält\n- Im Gegensatz zu Focus benötigt das **Bubbling des Click-Custom-Events** kein Warten auf die Theme-Bereitschaft (`data-themed`). Programmatische/delegierte Clicks (z. B. über `delegateClick()`) warten hingegen bewusst auf `data-themed`, um konsistentes visuelles Feedback und Fokus-Styling sicherzustellen.\n",
331
+ "code": "# Click Event Bubble/Emission Concept\n\nBeschreibt, wie Click-Events durch die KoliBri-Komponentenschichten propagiert werden: HTML5-Element im Shadow DOM → Host-Element (als Custom Event).\n\n## Überblick\n\nKoliBri Web Components verwenden Shadow DOM für Style-Isolation. Native Click-Events von Elementen innerhalb eines Shadow DOM geben zwar durch `composed: true` den Shadow-Grenzwert durch, berichten jedoch den Shadow Host als `event.target` – das eigentliche innere Element ist außen nicht sichtbar. Außerdem würde bei mehrfach verschachtelten Komponenten ein unkontrolliertes Durchsickern von Click-Events zu unerwünschtem Verhalten führen.\n\nKoliBri löst dieses Problem mit einem kontrollierten Zwei-Kanal-System:\n\n1. **Callback-Kanal** (`_on.onClick`) – direkter JavaScript-Callback, erhält das korrigierte Event-Target\n2. **DOM-Event-Kanal** – ein `CustomEvent` mit `composed: true` wird vom Host-Element neu ausgelöst\n\n## Architektur\n\n### Der Zwei-Kanal-Ansatz\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ Äußeres Konsumenten-Element │\n│ │\n│ element.addEventListener('click', handler) (2) │\n│ OR: _on={{ onClick: handler }} (1) │\n└──────────────────────────────┬───────────────────────────────────┘\n CustomEvent│ bubbles, composed (2)\n │ dispatchDomEvent(host, KolEvent.click)\n┌──────────────────────────────┴───────────────────────────────────┐\n│ Shadow Component: kol-button / kol-link (shadow: true) │\n│ Handler aus BaseButtonWebComponent / BaseLinkWebComponent │\n│ │\n│ handleClick(event) { │\n│ event.stopPropagation() ← native click abfangen │\n│ setEventTarget(event, ctaRef.el) ← Target korrigieren (1) │\n│ _on?.onClick(event, value) ← Callback aufrufen (1) │\n│ dispatchDomEvent(host, KolEvent.click, value) ← Event (2) │\n│ } │\n└──────────────────────────────┬───────────────────────────────────┘\n native │ click (stopPropagation verhindert Austritt)\n MouseEvent │\n┌──────────────────────────────┴───────────────────────────────────┐\n│ HTML5 Element: <button> / <a> (Functional Component) │\n│ Ursprung des nativen Click-Events │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n### Warum `event.stopPropagation()` bei Buttons?\n\nNative Click-Events haben `composed: true` und passieren die Shadow-DOM-Grenze; außen erscheint dann der Host als `event.target`. Das Durchsickern des nativen Events nach außen würde:\n\n- neben dem Custom Event ein zweites `click` am Host auslösen\n- die Callback-/DOM-Event-Dualität untergraben, da Konsumenten beide Signale erhalten würden\n\nDeshalb wird die native Propagation mit `stopPropagation()` unterbrochen und ein kontrolliertes\nCustom Event vom Host-Element neu ausgelöst.\n\n> **Hinweis zu Links:** Der Link-Handler ruft kein `stopPropagation()` auf. Die native Navigation\n> des `<a>`-Elements wird bei `_disabled: true` über `event.preventDefault()` unterbunden; in diesem\n> Fall entfallen Callback und Custom Event.\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Sortier-Buttons von `kol-table-stateless` oder die Buttons von `kol-pagination`), rendert sie deren Functional Component über ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/docs/ARC42-SKELETON.md#embedded-components-items)). Das Item übernimmt dieselben Schritte wie der Handler oben, dispatcht das Custom Event aber auf dem Wurzelknoten der Functional Component (`.kol-button`, `.kol-link`). Von dort bubblet es mit `composed: true` durch den Shadow DOM der einbettenden Komponente und über deren Host nach außen.\n\n## Utility-Funktionen und Typen\n\n### `dispatchDomEvent(target, event, detail)` — `packages/components/src/utils/events.ts`\n\nErstellt ein `CustomEvent` und dispatcht es vom Ziel-Element.\n\n```typescript\nfunction dispatchDomEvent<T>(target: HTMLElement, event: KolEvent, detail?: T) {\n\ttarget.dispatchEvent(createKoliBriEvent<T>(event, detail));\n}\n```\n\nDas zugrundeliegende Event wird mit diesen Optionen erstellt:\n\n```typescript\nconst DEFAULT_OPTIONS = {\n\tbubbles: true,\n\tcancelable: true,\n\tcomposed: true,\n} as const;\n```\n\n- **`bubbles: true`** — Das Event steigt im DOM nach oben\n- **`composed: true`** — Das Event kann Shadow-DOM-Grenzen passieren\n- **`cancelable: true`** — Das Event kann mit `preventDefault()` abgebrochen werden\n- **`detail`** — Trägt den Komponentenwert (z. B. `_value` bei Buttons, `_href` bei Links)\n\n### `KolEvent` — `packages/components/src/utils/events.ts`\n\nEnum aller Event-Namen, die KoliBri dispatcht:\n\n```typescript\nenum KolEvent {\n\tblur = 'blur',\n\tchange = 'change',\n\tclick = 'click',\n\tfocus = 'focus',\n\tinput = 'input',\n\t// ...weitere Events\n}\n```\n\nDer Event-Name `KolEvent.click` entspricht dem String `\"click\"`.\n\n### `setEventTarget(event, element)` — `packages/components/src/schema`\n\nKorrigiert das `target` eines Events auf das angegebene Element. Wird vor dem Callback-Aufruf\nverwendet, damit der Konsument das innere HTML5-Element (z. B. `<button>`, `<a>`) als Target erhält.\n\n### Callback-Typen — `packages/components/src/schema/types/callbacks.ts`\n\n```typescript\nexport type EventCallback<E extends Event> = (event: E) => void;\nexport type EventValueOrEventCallback<E extends Event, V> = ((event: E, value: V) => void) | EventCallback<E>;\n```\n\n- `EventCallback<E>` — einfacher Event-Handler ohne Wert\n- `EventValueOrEventCallback<E, V>` — Handler mit optionalem Komponentenwert als zweitem Argument\n\n## Umsetzung in Komponenten\n\n### Interaktive Elemente (Button, Link)\n\nDie Handler liegen in den gemeinsamen Basisklassen und werden der Functional Component als `handleClick` bzw. `handleAnchorClick` übergeben.\n\n#### Button — `BaseButtonWebComponent` (`packages/components/src/components/button/base.tsx`)\n\n```typescript\nprotected readonly handleClick = (event: MouseEvent): void => {\n\tevent.stopPropagation(); // Natives Event abfangen\n\tthis.tooltipBehavior.hideTooltip();\n\n\tconst type = this.getRenderProp('type');\n\tif (type === 'submit') {\n\t\tpropagateSubmitEventToForm({ form: this.host, ref: this.ctaRef.el });\n\t} else if (type === 'reset') {\n\t\tpropagateResetEventToForm({ form: this.host, ref: this.ctaRef.el });\n\t} else {\n\t\tthis.formAssociation.setFormAssociatedValue(this.formValue);\n\n\t\tconst onClick = this.getRenderProp('on').onClick;\n\t\tif (typeof onClick === 'function') {\n\t\t\tsetEventTarget(event, this.ctaRef.el); // Target korrigieren\n\t\t\tonClick(event, this.formValue); // (1) Callback\n\t\t}\n\t}\n\n\tif (this.host) {\n\t\tdispatchDomEvent(this.host, KolEvent.click, this.formValue); // (2) DOM-Event\n\t}\n};\n```\n\n#### Link — `BaseLinkWebComponent` (`packages/components/src/components/link/base.tsx`)\n\n```typescript\nprotected readonly handleAnchorClick = (event: Event): void => {\n\tthis.tooltipBehavior.hideTooltip();\n\tif (this.getRenderProp('disabled') === true) {\n\t\tevent.preventDefault(); // Navigation verhindern\n\t\treturn;\n\t}\n\tconst href = this.getRenderProp('href');\n\tconst on = this.getRenderProp('on');\n\tif (typeof on?.onClick === 'function') {\n\t\tsetEventTarget(event, this.ctaRef.el); // Target korrigieren\n\t\ton.onClick(event, href); // (1) Callback\n\t}\n\tif (this.host) {\n\t\tdispatchDomEvent(this.host, KolEvent.click, href); // (2) DOM-Event\n\t}\n};\n```\n\nDie Tastaturbedienung braucht keinen eigenen Handler: Enter auf einem `<a href>` und Enter/Space auf einem `<button>` lösen nativ ein `click` aus.\n\n### Input-Elemente\n\nInput-Elemente (z. B. `kol-input-text`, `kol-input-checkbox`) leiten Click-Events ebenfalls\nüber den `_on`-Prop-Mechanismus weiter. Der `InputTypeOnClick`-Typ ist Teil des Standard-Event-Sets:\n\n```typescript\n// packages/components/src/schema/types/input/types.ts\ntype InputTypeOnClick = {\n\t[Callback.onClick]?: EventCallback<Event>;\n};\n\nexport type InputTypeOnDefault = InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown;\n```\n\nDas Muster für Input-Komponenten ist analog zu Buttons: `onClick` im `_on`-Objekt + `dispatchDomEvent`.\n\n## Konsumenten-Perspektive\n\n```typescript\n// (1) Callback-Kanal — typsicher, erhält den Komponentenwert:\n<KolButton _label=\"Senden\" _on={{ onClick: (event, value) => console.log(value) }} />\n\n// (2) DOM-Event-Kanal — Standard-Web-API, z. B. für Framework-Integration:\ndocument.querySelector('kol-button').addEventListener('click', (event: CustomEvent) => {\n\tconst value = event.detail; // Komponentenwert aus event.detail\n});\n```\n\n### Vergleich der beiden Kanäle\n\n| Eigenschaft | Callback (`_on.onClick`) | DOM CustomEvent (`addEventListener`) |\n| --------------- | --------------------------------------------- | ----------------------------------------------- |\n| API | KoliBri-spezifisch | Standard Web API |\n| Event-Target | Korrigiert auf inneres HTML5-Element | Host-Element (`kol-button`, `kol-link`, etc.) |\n| Komponentenwert | Als zweites Argument `value` | In `event.detail` |\n| Typ | `EventValueOrEventCallback<MouseEvent, V>` | `CustomEvent<V>` |\n| Bubbles | Nein (direkter Funktionsaufruf) | Ja (`bubbles: true, composed: true`) |\n| Geeignet für | Direkte Framework-Integration (React, Vue...) | Vanilla JS, Event-Delegation, Framework-Adapter |\n\n## Zusammenfassung\n\n| Schritt | Was passiert |\n| ------- | ---------------------------------------------------------------------------- |\n| 1 | Nutzer klickt → nativer `MouseEvent` auf `<button>` / `<a>` |\n| 2 | Handler fängt Event ab, ruft `event.stopPropagation()` (nur Button) |\n| 3 | `setEventTarget(event, ctaRef.el)` korrigiert das Event-Target |\n| 4 | `_on?.onClick(event, value)` — Callback-Kanal wird bedient |\n| 5 | `dispatchDomEvent(host, KolEvent.click, value)` — neues Custom Event am Host |\n| 6 | Das Custom Event bubblet mit `composed: true` durch den DOM-Baum |\n\n**Wichtig:**\n\n- Das native Click-Event eines Buttons verlässt die Komponente **nicht** unkontrolliert\n- Das Custom Event trägt stets den **Komponentenwert** in `event.detail` (kein DOM-Wert)\n- `setEventTarget` stellt sicher, dass der Callback das **innere Element** als Target erhält\n- Im Gegensatz zu Focus benötigt das **Bubbling des Click-Custom-Events** kein Warten auf die Theme-Bereitschaft (`data-themed`). Programmatische/delegierte Clicks (z. B. über `delegateClick()`) warten hingegen bewusst auf `data-themed`, um konsistentes visuelles Feedback und Fokus-Styling sicherzustellen.\n",
332
332
  "kind": "doc"
333
333
  },
334
334
  {
@@ -337,7 +337,7 @@
337
337
  "name": "CLICK_PROPAGATION_CONCEPT",
338
338
  "description": "Beschreibt ein analoges Delegationskonzept zu Focus: Ein Klick auf den KoliBri-Host wird gezielt auf das primaere interaktive Innenelement weitergeleitet.",
339
339
  "path": "docs/CLICK_PROPAGATION_CONCEPT.md",
340
- "code": "# Click Delegation Concept\n\nBeschreibt ein analoges Delegationskonzept zu Focus: Ein Klick auf den KoliBri-Host wird gezielt auf das primaere interaktive Innenelement weitergeleitet.\n\n## Status\n\nDieses Dokument beschreibt das Click-Delegationskonzept sowie noch geplante Erweiterungen; Teile sind bereits implementiert, weitere folgen sukzessive.\n\n- Ist: Komponenten mit `@Method() click()` delegieren den Klick über den Decorator `@delegateClick('ctaRef')` (`packages/components/src/utils/element-interaction.ts`) mit `delegateClick`/`setClick` (`packages/components/src/utils/element-click.ts`) auf ihr primäres Innenelement.\n- Soll: Ein Reentrancy-Schutz gegen intern erneut entstehende Click-Events (siehe Kernidee 3).\n\n## Ziel\n\nWenn ein Konsument auf das Host-Element klickt (z. B. `kol-button`), soll nicht nur ein Event nach aussen signalisiert werden, sondern der Klick nach innen auf das primaere interaktive Element delegiert werden.\n\nBeispiele:\n\n- `kol-button` -> primaer: `<button class=\"kol-button__interactive-element\">` im Shadow DOM\n- `kol-link-button` -> primaer: `<a class=\"kol-link__interactive-element\">` im Shadow DOM\n- `kol-input-text` -> primaer: `<input>` im Shadow DOM\n\n## Architektur\n\n### Delegationsfluss (analog zu Focus)\n\nDie Functional Component einer Komponente rendert das primaere HTML5-Element direkt in den Shadow DOM der Komponente. Die Delegation hat deshalb genau eine Stufe:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Shadow Component: kol-button (shadow: true) │\n│ @Method() @delegateClick('ctaRef') click() │\n└─────────────────────────┬───────────────────────────────┘\n ↓ wartet auf data-themed, dann setClick(ctaRef.el)\n┌─────────────────────────────────────────────────────────┐\n│ HTML5 Element: <button> │\n│ tatsaechlich aktiviert (native click action) │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Buttons von `kol-pagination`), dann rendert sie deren Functional Component ueber ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/src/components/_skeleton/ARC42.md#embedded-components-items)). Ein eingebetteter Button ist kein eigenes Element und hat keine eigene `click()`-Methode; das `click()` der einbettenden Komponente zielt auf deren eigenes primaeres Element.\n\n## Kernideen\n\n1. Host-initiierter Klick wird nach innen delegiert, statt nur als Event nach aussen gebubbelt.\n2. Delegation fordert vor der Propagation immer `data-themed` am Host.\n3. (Geplant) Ein Reentrancy-Schutz soll Endlosschleifen durch intern erneut entstehende Click-Events verhindern; die aktuellen Hilfsfunktionen `delegateClick`/`setClick` enthalten diesen Schutz noch nicht.\n4. Nur primaere Interaktionselemente sind Delegationsziele.\n\n### Warum `data-themed` auch für Click zwingend ist\n\nTechnisch kann ein `element.click()` oft auch schon vor abgeschlossener Theme-Anwendung funktionieren.\nDas waere aber aus UX- und Test-Sicht nicht authentisch:\n\n- Der Nutzer klickt real auf sichtbare, fertig gerenderte Controls.\n- Ohne `data-themed` besteht das Risiko, dass Tests auf ein noch unsichtbares oder semantisch nicht final aufgebautes Element klicken.\n- Dadurch entstehen false positives: Der Test ist gruen, obwohl die reale Interaktion noch nicht stabil waere.\n\nDeshalb gilt analog zu Focus: Click-Delegation darf erst starten, wenn `data-themed` gesetzt ist.\n\n## Utility Functions\n\n### `delegateClick(host, callback)` — `packages/components/src/utils/element-click.ts`\n\nWartet zwingend auf Theme-Readiness und fuehrt dann die eigentliche Klick-Aktion aus.\n\n```typescript\nexport async function delegateClick(host: HTMLElement, callback: () => Promise<void>): Promise<void> {\n\ttry {\n\t\tif (!host.hasAttribute('data-themed')) {\n\t\t\tawait waitForThemed(host);\n\t\t}\n\t\tawait callback();\n\t} catch {\n\t\tthrow new Error(\n\t\t\t'The interactive element inside the KoliBri web component could not be clicked. Try calling the click method on the web component after a short delay again.',\n\t\t);\n\t}\n}\n```\n\n### `setClick(element)` — `packages/components/src/utils/element-click.ts`\n\nFuehrt den nativen Klick auf dem Ziel-Element aus und wiederholt ihn pro Animation Frame, solange das Element noch nicht sichtbar ist.\n\n```typescript\nexport async function setClick(element: HTMLElement): Promise<void> {\n\tlet attempts = 0;\n\tdo {\n\t\tif (element) {\n\t\t\telement.click();\n\t\t}\n\t\tawait new Promise((r) => requestAnimationFrame(r));\n\t\tattempts++;\n\t} while (!isElementVisible(element) && attempts < MAX_CLICK_ATTEMPTS);\n}\n```\n\n### `isElementVisible(element)` (intern)\n\nPrueft ueber `getBoundingClientRect()`, ob das Element sichtbar ist (Breite und Hoehe > 0).\n\n### `waitForThemed(host)` — `packages/components/src/utils/element-themed.ts`\n\nWird gemeinsam mit der Focus-Delegation genutzt; Timeout nach 5000 ms.\n\n### Konstanten\n\n```typescript\nconst MAX_CLICK_ATTEMPTS = 3;\n```\n\n## Komponentenregeln\n\n### Interface\n\nAlle klickbaren Komponenten implementieren das `ClickableElement`-Interface aus `packages/components/src/schema/interfaces/ClickableElement.ts`:\n\n```typescript\nexport interface ClickableElement {\n\tclick(): Promise<void>;\n}\n```\n\n### API-Kontrakt für alle Web Components\n\nIn allen klickbaren Web Components gilt derselbe oeffentliche Methodenvertrag:\n\n```typescript\n@Method()\npublic async click(): Promise<void> {\n\t// komponentenspezifische Delegation\n}\n```\n\nDamit erzwingen wir API-Homogenitaet analog zum HTML-Standard.\n\n### Regel 1: Delegation ueber den Decorator\n\nDas primaere Element haelt ein `CtaRef` aus `createCtaRef()`, die Methode entsteht ueber `@delegateClick`:\n\n```typescript\n@Component({ tag: 'kol-button', shadow: true })\nexport class KolButton extends BaseButtonWebComponent implements ButtonProps, ClickableElement {\n\t@Element() protected readonly host?: HTMLKolButtonElement;\n\n\t// In der Basisklasse: protected readonly ctaRef = createCtaRef<HTMLButtonElement>();\n\t// Die Functional Component setzt ihn am nativen Element: <button ref={ctaRef} …>\n\n\t@Method()\n\t@delegateClick('ctaRef')\n\tpublic async click(): Promise<void> {}\n}\n```\n\nHinweise:\n\n- `delegateClick` wartet zwingend auf `data-themed` vor der Klick-Delegation, um konsistentes visuelles Feedback zu sichern.\n- Liefert das Praedikat von `createCtaRef(isInactive)` `true`, liest sich `ctaRef.el` als `undefined` und `click()` tut nichts, wie bei einem nativ deaktivierten Control.\n\n### Regel 2: Primaeres Ziel je Komponente festlegen\n\nJede interaktive Komponente dokumentiert genau ein primaeres Klickziel:\n\n- `kol-button`: interner `<button>`\n- `kol-link`: interner `<a>`\n- `kol-input-*`: interner `<input>` bzw. `<textarea>`\n- `kol-combobox`: interner `<input>`\n\n## Event-Semantik\n\nDas Delegationskonzept ersetzt nicht die bestehende Event-API (`_on.onClick`, `dispatchDomEvent`), sondern ordnet die Reihenfolge:\n\n1. Host-Klick wird nach innen delegiert.\n2. Das innere Element verarbeitet den nativen Klick.\n3. Bestehende Callback-/DOM-Event-Mechanismen bleiben unveraendert aktiv.\n\nDamit bleibt die oeffentliche API kompatibel.\n\n## Abgrenzung zu aktuellem Bubble-Konzept\n\n- Bubble-Konzept: Ereignis von innen nach aussen signalisieren.\n- Delegationskonzept: Interaktion von aussen nach innen ausfuehren.\n\nBeides ist kombinierbar und sinnvoll:\n\n- nach innen delegieren fuer robuste Aktivierung durch Host-Interaktion\n- nach aussen emittieren fuer API/Framework-Kompatibilitaet\n\n## Akzeptanzkriterien\n\n1. Klick auf den Host (`event.target === host`) aktiviert das primaere Innenelement.\n2. Klick direkt auf das Innenelement behaelt sein heutiges Verhalten.\n3. Keine doppelte Ausfuehrung von Click-Callbacks.\n4. Keine Rekursion/Endlosschleife durch delegierte Klicks.\n5. Verhalten ist identisch fuer Maus und Tastaturaktivierung (Enter/Space), soweit komponentenspezifisch anwendbar.\n\n## Teststrategie\n\n### Unit Tests\n\n- `delegateClick` wartet verpflichtend auf `data-themed` analog zu `delegateFocus`.\n- Timeout-Fehler wird mit nutzerfreundlicher Message geworfen.\n- Reentrancy-Guard verhindert zweite Delegation.\n- Kein Click-Versuch vor `data-themed` (verhindert Interaktion mit unsichtbaren/fruehen DOM-Zustaenden).\n\n### E2E Tests\n\n- Host direkt klicken -> primaere Aktion wird einmal ausgefuehrt.\n- Inneres Element klicken -> Aktion wird ebenfalls einmal ausgefuehrt.\n- `_on.onClick` und DOM-Event werden jeweils genau einmal beobachtet.\n\n#### TypeScript-Typisierung in E2E Tests\n\nBei DOM-Zugriffen in E2E-Tests muss zwischen KoliBri Web Components und nativen HTML-Elementen unterschieden werden, da der `click()`-Aufruf auf KoliBri-Komponenten **asynchron** ist (im Gegensatz zum synchronen nativen `click()`):\n\n- **KoliBri Web Components** erhalten den spezifischen KoliBri-Elementtyp, z. B. `HTMLKolButtonElement`, `HTMLKolLinkElement`, `HTMLKolInputTextElement`. Nur so steht die typisierte `async click()`-Methode der Komponente zur Verfuegung.\n- **Native HTML-Elemente** erhalten den entsprechenden Standard-Typ, z. B. `HTMLButtonElement`, `HTMLAnchorElement`, `HTMLInputElement`.\n\nBeispiel:\n\n```typescript\n// KoliBri Web Component: click() ist async und muss awaited werden\nconst kolButton = document.querySelector('kol-button') as HTMLKolButtonElement;\nawait kolButton.click();\n\n// Natives HTML-Element: click() ist synchron\nconst nativeButton = document.querySelector('button') as HTMLButtonElement;\nnativeButton.click();\n```\n\n**Falsch** (kein await, falscher Typ):\n\n```typescript\n// Fehler: Element.click() ist synchron und nicht die KoliBri-Delegation\nconst kolButton = document.querySelector('kol-button') as HTMLElement;\nkolButton.click(); // loest keinen delegierten Klick aus\n```\n\n**Regel**: Immer `await` verwenden, wenn `click()` auf einer KoliBri Web Component aufgerufen wird. Das Weglassen von `await` fuehrt dazu, dass der Klick vor abgeschlossener Theme-Bereitschaft und Delegation ausgefuehrt werden koennte oder der Test zu frueh weiterlaeuft.\n\n## Zusammenfassung\n\nAnalog zu Focus sollte Click als echte Delegation von Host nach innen modelliert werden.\n\n- Focus: Host `focus()` -> inneres Element `focus()`\n- Click (Soll): Host-Klick -> inneres Element `click()`\n\nSo wird die Komponente aus Konsumentensicht konsistent: Der Host ist die oeffentliche Interaktionsflaeche, die innere Aktivierung bleibt korrekt und kontrolliert.\n",
340
+ "code": "# Click Delegation Concept\n\nBeschreibt ein analoges Delegationskonzept zu Focus: Ein Klick auf den KoliBri-Host wird gezielt auf das primaere interaktive Innenelement weitergeleitet.\n\n## Status\n\nDieses Dokument beschreibt das Click-Delegationskonzept sowie noch geplante Erweiterungen; Teile sind bereits implementiert, weitere folgen sukzessive.\n\n- Ist: Komponenten mit `@Method() click()` delegieren den Klick über den Decorator `@delegateClick('ctaRef')` (`packages/components/src/utils/element-interaction.ts`) mit `delegateClick`/`setClick` (`packages/components/src/utils/element-click.ts`) auf ihr primäres Innenelement.\n- Soll: Ein Reentrancy-Schutz gegen intern erneut entstehende Click-Events (siehe Kernidee 3).\n\n## Ziel\n\nWenn ein Konsument auf das Host-Element klickt (z. B. `kol-button`), soll nicht nur ein Event nach aussen signalisiert werden, sondern der Klick nach innen auf das primaere interaktive Element delegiert werden.\n\nBeispiele:\n\n- `kol-button` -> primaer: `<button class=\"kol-button__interactive-element\">` im Shadow DOM\n- `kol-link-button` -> primaer: `<a class=\"kol-link__interactive-element\">` im Shadow DOM\n- `kol-input-text` -> primaer: `<input>` im Shadow DOM\n\n## Architektur\n\n### Delegationsfluss (analog zu Focus)\n\nDie Functional Component einer Komponente rendert das primaere HTML5-Element direkt in den Shadow DOM der Komponente. Die Delegation hat deshalb genau eine Stufe:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Shadow Component: kol-button (shadow: true) │\n│ @Method() @delegateClick('ctaRef') click() │\n└─────────────────────────┬───────────────────────────────┘\n ↓ wartet auf data-themed, dann setClick(ctaRef.el)\n┌─────────────────────────────────────────────────────────┐\n│ HTML5 Element: <button> │\n│ tatsaechlich aktiviert (native click action) │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Buttons von `kol-pagination`), dann rendert sie deren Functional Component ueber ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/docs/ARC42-SKELETON.md#embedded-components-items)). Ein eingebetteter Button ist kein eigenes Element und hat keine eigene `click()`-Methode; das `click()` der einbettenden Komponente zielt auf deren eigenes primaeres Element.\n\n## Kernideen\n\n1. Host-initiierter Klick wird nach innen delegiert, statt nur als Event nach aussen gebubbelt.\n2. Delegation fordert vor der Propagation immer `data-themed` am Host.\n3. (Geplant) Ein Reentrancy-Schutz soll Endlosschleifen durch intern erneut entstehende Click-Events verhindern; die aktuellen Hilfsfunktionen `delegateClick`/`setClick` enthalten diesen Schutz noch nicht.\n4. Nur primaere Interaktionselemente sind Delegationsziele.\n\n### Warum `data-themed` auch für Click zwingend ist\n\nTechnisch kann ein `element.click()` oft auch schon vor abgeschlossener Theme-Anwendung funktionieren.\nDas waere aber aus UX- und Test-Sicht nicht authentisch:\n\n- Der Nutzer klickt real auf sichtbare, fertig gerenderte Controls.\n- Ohne `data-themed` besteht das Risiko, dass Tests auf ein noch unsichtbares oder semantisch nicht final aufgebautes Element klicken.\n- Dadurch entstehen false positives: Der Test ist gruen, obwohl die reale Interaktion noch nicht stabil waere.\n\nDeshalb gilt analog zu Focus: Click-Delegation darf erst starten, wenn `data-themed` gesetzt ist.\n\n## Utility Functions\n\n### `delegateClick(host, callback)` — `packages/components/src/utils/element-click.ts`\n\nWartet zwingend auf Theme-Readiness und fuehrt dann die eigentliche Klick-Aktion aus.\n\n```typescript\nexport async function delegateClick(host: HTMLElement, callback: () => Promise<void>): Promise<void> {\n\ttry {\n\t\tif (!host.hasAttribute('data-themed')) {\n\t\t\tawait waitForThemed(host);\n\t\t}\n\t\tawait callback();\n\t} catch {\n\t\tthrow new Error(\n\t\t\t'The interactive element inside the KoliBri web component could not be clicked. Try calling the click method on the web component after a short delay again.',\n\t\t);\n\t}\n}\n```\n\n### `setClick(element)` — `packages/components/src/utils/element-click.ts`\n\nFuehrt den nativen Klick auf dem Ziel-Element aus und wiederholt ihn pro Animation Frame, solange das Element noch nicht sichtbar ist.\n\n```typescript\nexport async function setClick(element: HTMLElement): Promise<void> {\n\tlet attempts = 0;\n\tdo {\n\t\tif (element) {\n\t\t\telement.click();\n\t\t}\n\t\tawait new Promise((r) => requestAnimationFrame(r));\n\t\tattempts++;\n\t} while (!isElementVisible(element) && attempts < MAX_CLICK_ATTEMPTS);\n}\n```\n\n### `isElementVisible(element)` (intern)\n\nPrueft ueber `getBoundingClientRect()`, ob das Element sichtbar ist (Breite und Hoehe > 0).\n\n### `waitForThemed(host)` — `packages/components/src/utils/element-themed.ts`\n\nWird gemeinsam mit der Focus-Delegation genutzt; Timeout nach 5000 ms.\n\n### Konstanten\n\n```typescript\nconst MAX_CLICK_ATTEMPTS = 3;\n```\n\n## Komponentenregeln\n\n### Interface\n\nAlle klickbaren Komponenten implementieren das `ClickableElement`-Interface aus `packages/components/src/schema/interfaces/ClickableElement.ts`:\n\n```typescript\nexport interface ClickableElement {\n\tclick(): Promise<void>;\n}\n```\n\n### API-Kontrakt für alle Web Components\n\nIn allen klickbaren Web Components gilt derselbe oeffentliche Methodenvertrag:\n\n```typescript\n@Method()\npublic async click(): Promise<void> {\n\t// komponentenspezifische Delegation\n}\n```\n\nDamit erzwingen wir API-Homogenitaet analog zum HTML-Standard.\n\n### Regel 1: Delegation ueber den Decorator\n\nDas primaere Element haelt ein `CtaRef` aus `createCtaRef()`, die Methode entsteht ueber `@delegateClick`:\n\n```typescript\n@Component({ tag: 'kol-button', shadow: true })\nexport class KolButton extends BaseButtonWebComponent implements ButtonProps, ClickableElement {\n\t@Element() protected readonly host?: HTMLKolButtonElement;\n\n\t// In der Basisklasse: protected readonly ctaRef = createCtaRef<HTMLButtonElement>();\n\t// Die Functional Component setzt ihn am nativen Element: <button ref={ctaRef} …>\n\n\t@Method()\n\t@delegateClick('ctaRef')\n\tpublic async click(): Promise<void> {}\n}\n```\n\nHinweise:\n\n- `delegateClick` wartet zwingend auf `data-themed` vor der Klick-Delegation, um konsistentes visuelles Feedback zu sichern.\n- Liefert das Praedikat von `createCtaRef(isInactive)` `true`, liest sich `ctaRef.el` als `undefined` und `click()` tut nichts, wie bei einem nativ deaktivierten Control.\n\n### Regel 2: Primaeres Ziel je Komponente festlegen\n\nJede interaktive Komponente dokumentiert genau ein primaeres Klickziel:\n\n- `kol-button`: interner `<button>`\n- `kol-link`: interner `<a>`\n- `kol-input-*`: interner `<input>` bzw. `<textarea>`\n- `kol-combobox`: interner `<input>`\n\n## Event-Semantik\n\nDas Delegationskonzept ersetzt nicht die bestehende Event-API (`_on.onClick`, `dispatchDomEvent`), sondern ordnet die Reihenfolge:\n\n1. Host-Klick wird nach innen delegiert.\n2. Das innere Element verarbeitet den nativen Klick.\n3. Bestehende Callback-/DOM-Event-Mechanismen bleiben unveraendert aktiv.\n\nDamit bleibt die oeffentliche API kompatibel.\n\n## Abgrenzung zu aktuellem Bubble-Konzept\n\n- Bubble-Konzept: Ereignis von innen nach aussen signalisieren.\n- Delegationskonzept: Interaktion von aussen nach innen ausfuehren.\n\nBeides ist kombinierbar und sinnvoll:\n\n- nach innen delegieren fuer robuste Aktivierung durch Host-Interaktion\n- nach aussen emittieren fuer API/Framework-Kompatibilitaet\n\n## Akzeptanzkriterien\n\n1. Klick auf den Host (`event.target === host`) aktiviert das primaere Innenelement.\n2. Klick direkt auf das Innenelement behaelt sein heutiges Verhalten.\n3. Keine doppelte Ausfuehrung von Click-Callbacks.\n4. Keine Rekursion/Endlosschleife durch delegierte Klicks.\n5. Verhalten ist identisch fuer Maus und Tastaturaktivierung (Enter/Space), soweit komponentenspezifisch anwendbar.\n\n## Teststrategie\n\n### Unit Tests\n\n- `delegateClick` wartet verpflichtend auf `data-themed` analog zu `delegateFocus`.\n- Timeout-Fehler wird mit nutzerfreundlicher Message geworfen.\n- Reentrancy-Guard verhindert zweite Delegation.\n- Kein Click-Versuch vor `data-themed` (verhindert Interaktion mit unsichtbaren/fruehen DOM-Zustaenden).\n\n### E2E Tests\n\n- Host direkt klicken -> primaere Aktion wird einmal ausgefuehrt.\n- Inneres Element klicken -> Aktion wird ebenfalls einmal ausgefuehrt.\n- `_on.onClick` und DOM-Event werden jeweils genau einmal beobachtet.\n\n#### TypeScript-Typisierung in E2E Tests\n\nBei DOM-Zugriffen in E2E-Tests muss zwischen KoliBri Web Components und nativen HTML-Elementen unterschieden werden, da der `click()`-Aufruf auf KoliBri-Komponenten **asynchron** ist (im Gegensatz zum synchronen nativen `click()`):\n\n- **KoliBri Web Components** erhalten den spezifischen KoliBri-Elementtyp, z. B. `HTMLKolButtonElement`, `HTMLKolLinkElement`, `HTMLKolInputTextElement`. Nur so steht die typisierte `async click()`-Methode der Komponente zur Verfuegung.\n- **Native HTML-Elemente** erhalten den entsprechenden Standard-Typ, z. B. `HTMLButtonElement`, `HTMLAnchorElement`, `HTMLInputElement`.\n\nBeispiel:\n\n```typescript\n// KoliBri Web Component: click() ist async und muss awaited werden\nconst kolButton = document.querySelector('kol-button') as HTMLKolButtonElement;\nawait kolButton.click();\n\n// Natives HTML-Element: click() ist synchron\nconst nativeButton = document.querySelector('button') as HTMLButtonElement;\nnativeButton.click();\n```\n\n**Falsch** (kein await, falscher Typ):\n\n```typescript\n// Fehler: Element.click() ist synchron und nicht die KoliBri-Delegation\nconst kolButton = document.querySelector('kol-button') as HTMLElement;\nkolButton.click(); // loest keinen delegierten Klick aus\n```\n\n**Regel**: Immer `await` verwenden, wenn `click()` auf einer KoliBri Web Component aufgerufen wird. Das Weglassen von `await` fuehrt dazu, dass der Klick vor abgeschlossener Theme-Bereitschaft und Delegation ausgefuehrt werden koennte oder der Test zu frueh weiterlaeuft.\n\n## Zusammenfassung\n\nAnalog zu Focus sollte Click als echte Delegation von Host nach innen modelliert werden.\n\n- Focus: Host `focus()` -> inneres Element `focus()`\n- Click (Soll): Host-Klick -> inneres Element `click()`\n\nSo wird die Komponente aus Konsumentensicht konsistent: Der Host ist die oeffentliche Interaktionsflaeche, die innere Aktivierung bleibt korrekt und kontrolliert.\n",
341
341
  "kind": "doc"
342
342
  },
343
343
  {
@@ -379,7 +379,7 @@
379
379
  "name": "CONTRIBUTING",
380
380
  "description": "We would love for you to contribute to KoliBriand help make it even better than it is today! As a contributor, we ask that you follow the following guidelines:",
381
381
  "path": "CONTRIBUTING.md",
382
- "code": "# Contributing\n\nWe would love for you to contribute to **KoliBri**and help make it even better than it is today! As a contributor, we ask that you follow the following guidelines:\n\n- [Contributing](#contributing)\n - [Code of Conduct](#code-of-conduct)\n - [Questions and problems](#questions-and-problems)\n - [Report an error](#report-an-error)\n - [Further development](#further-development)\n - [Git flow](#git-flow)\n - [Pull Request Guidelines](#pull-request-guidelines)\n - [Developing](#developing)\n - [Develop new component](#develop-new-component)\n - [Switching between branches](#switching-between-branches)\n - [Back porting to older Major-Versions](#back-porting-to-older-major-versions)\n - [Snapshot Testing for Visual Changes](#snapshot-testing-for-visual-changes)\n - [How to Update Snapshots](#how-to-update-snapshots)\n\n## Code of Conduct\n\nHelp us keep **KoliBri** open and inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Questions and problems\n\nPlease do not create issue tickets for general support questions. We want to use the ticket system for tracking bug reports and feature requests.\n\nInstead, we recommend first checking [Stack Overflow](https://stackoverflow.com/questions/tagged/kolibri) to see whether someone else has already solved the question or problem. You can also create new questions with the tag “hummingbird”.\nTo save your time and ours, we will close all general questions in the ticket system and redirect those asking to Stack Overflow.\n\nIf you would like to contact us, please send us an email to [kolibri@itzbund.de](mailto:kolibri@itzbund.de).\n\n## Report an error\n\nIf you find an error in the source code, you can report it to our ticket system.\n\nIt would be even better if you suggested a solution to us as a pull request.\n\n## Further development\n\nYou can request new features by submitting an issue to our ticket system. If you would like to implement a new function, please note the following steps for further action:\n\n- It is helpful to read the KoliBri [architecture concept](https://public-ui.github.io/docs/concepts/architecture) before implementing.\n- For major innovations, please create a ticket with the description of the new function.\n- For small innovations, you can offer and justify the implementation directly as a pull request.\n\n### Git flow\n\nWe work according to the Git flow: https://medium.com/android-news/gitflow-with-github-c675aa4f606a\n\n### Pull Request Guidelines\n\nWhen creating a pull request, please follow these guidelines:\n\n- **PR Title:** The pull request title must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This is enforced by automated validation in our CI pipeline.\n- **PR Title Format:** `<type>: <description>` or `<type>(<scope>): <description>`\n- **Allowed Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`\n- **Description:** The description must start with a letter (lowercase or uppercase) and clearly explain the change.\n\n**Examples of valid PR titles:**\n\n- `feat: add new button component`\n- `fix: resolve navigation issue on mobile devices`\n- `docs: update installation instructions`\n- `refactor(components): simplify input validation logic`\n- `test(visual-tests): Axe-Verstöße wieder als Build-Breaker auswerten`\n\n**Examples of invalid PR titles:**\n\n- `Add new feature` (missing type prefix)\n- `feat: 1st feature` (description must start with a letter)\n- `feature: add new button` (invalid type, should be `feat`)\n\n### Developing\n\n1. For contributing, you need a [GitHub account](https://github.com/login)\n2. Fork [our repository](https://github.com/public-ui/kolibri) on GitHub\n3. Open your preferred command line interface\n4. Clone the forked repository via HTTPS to your local machine. The VS Code GitHub extension can handle authentication.\n5. Navigate the project root directory\n6. Create a new branch for your changes\n7. Install Node.js version 22\n8. [Install PNPM](https://pnpm.io/installation) on you local machine\n9. Follow the [daily workflow](#daily-workflow) below\n\nRun ESLint across the repository with `pnpm lint` (or `pnpm lint:eslint` to invoke ESLint directly); the configuration lives in `packages/*/eslint.config.cjs`. Formatting is handled by Prettier via `pnpm format`, so run format first to keep ESLint focused on code-quality rules rather than style drift.\n\n### Daily workflow\n\nEvery package in the monorepo builds itself, and dependents always consume the built output of the\npackages they reference. The chain is kolicons → components → adapters → themes → sample →\npresentation. The order comes from the workspace dependencies: `pnpm -r build` builds every package\nexactly once, topologically sorted, and no package's build builds another package. No `dev` or\n`preview` script builds anything for you, so the workflow is always the same:\n\n```bash\ngit pull\npnpm i\npnpm -r build\n\n# One terminal per package you are changing\npnpm --filter @public-ui/components dev\npnpm --filter @public-ui/theme-default dev\n\n# The app to look at, http://localhost:9191\npnpm --filter @public-ui/presentation dev\n```\n\nThen work on the code: each watcher rebuilds its own package and the presentation app reloads.\n\n- A `dev` script exists in `@public-ui/components`, every theme package (`@public-ui/theme-bwst`,\n `-default`, `-desy`, `-ecl`, `-kern`) and `@public-ui/mcp`. Packages without one, such as the\n adapters or the icons, are rebuilt with `pnpm --filter <package> build` after a change.\n- Never run a build while a watcher is active. `pnpm -r build`, `pnpm build:deps` and the\n components `build` start with `pnpm clear` and delete the output the watcher owns. Stop the\n watchers, build, then start `dev` again.\n\n### VS Code Setup\n\nWe recommend using [Visual Studio Code](https://code.visualstudio.com/):\n\n- Install the Prettier and ESLint extensions.\n- Enable \"Format on Save\" in your settings.\n\n### Tests\n\nAll tests run via GitHub Actions when you open a pull request. Monitor them under the **Actions** tab.\n\n### Develop new component\n\nRefer to [new component](docs/tutorials/NEW_COMPONENT.md) tutorial.\n\n### Switching between branches\n\nAfter a branch switch, dependencies and build output may no longer match the code. Stop all\nwatchers and repeat the [daily workflow](#daily-workflow) from `pnpm i` on: reinstall, build\neverything, then start `dev` in the packages you are working on.\n\n### Back porting to older Major-Versions\n\nBy default, development is carried out in the `development` branch for the following version. However, if it becomes necessary to provide an issue for an older major release, such as version 1.x.x, the code change must also be merged into the corresponding release branch. In this case, it would be the `release/1` branch. It is important that the branch that was created from the `develop` is not merged into the release branch, as otherwise the next patch version will receive all the changes from the current development status.\nThe simplest procedure is therefore to create a new branch from the release branch (e.g. `release/1`) and transfer the individual commits of the feature branch from the `develop` to the new branch using cherry-picking. This branch can then be merged into the release branch as normal with a new pull request.\n\n### Visual Review for Visual Changes\n\nThe Continuous Integration (CI) pipeline takes screenshots of the React sample app in every theme and compares them with the baseline of the base branch. The screenshots are **not** stored in git: every push to `develop`, `main` and `release/*` publishes them as the artifact `visual-baseline-<package>`, and a pull request compares against the artifact of the commit it is merged with.\n\nWhen you introduce visual modifications to components, themes or the React sample app:\n\n1. The `visual-tests (<package>)` jobs report the differences. That is expected – there is nothing to regenerate or commit.\n2. The bot comment **📸 Visual Review** on the pull request links the review page (`https://public-ui.github.io/kolibri/visual/?pr=<number>`), where every changed, added and removed screenshot can be inspected side by side, with a slider, as onion skin or as diff.\n3. A reviewer with write access approves (or rejects) the screenshots there – directly with a fine-grained GitHub token, or by pasting the generated comment on the pull request, as a comment or as the text of a review. The commit status **Visual Review** turns green once everything is approved; approvals are bound to the screenshot content and survive later pushes that do not change the screenshot again.\n\nThe full process is described in [docs/visual-review.md](docs/visual-review.md).\n\n#### Running the visual tests locally\n\n```bash\npnpm snapshots:pull # download the current develop baseline into the snapshot folders (needs `gh auth login`)\npnpm --filter @public-ui/theme-default test # compare; the result is written to packages/themes/default/visual-report/\npnpm test:update:docker default # regenerate a baseline locally in the pinned Playwright container\n```\n\nScreenshots are platform specific (font rendering), so only the Docker variant produces files that match the CI.\n\n#### Text snapshots of the unit tests\n\nThe `__snapshots__` files of the unit tests (components, hydrate, hydrate-server) stay in git. Update them with `pnpm test:update:unit`, or run the `03 - Update Snapshots` action on your branch:\n\n```bash\ngh workflow run update-snapshots.yml -r `git rev-parse --abbrev-ref HEAD`\n```\n",
382
+ "code": "# Contributing\n\nWe would love for you to contribute to **KoliBri**and help make it even better than it is today! As a contributor, we ask that you follow the following guidelines:\n\n- [Contributing](#contributing)\n - [Code of Conduct](#code-of-conduct)\n - [Questions and problems](#questions-and-problems)\n - [Report an error](#report-an-error)\n - [Further development](#further-development)\n - [Git flow](#git-flow)\n - [Pull Request Guidelines](#pull-request-guidelines)\n - [Developing](#developing)\n - [Develop new component](#develop-new-component)\n - [Switching between branches](#switching-between-branches)\n - [Back porting to older Major-Versions](#back-porting-to-older-major-versions)\n - [Snapshot Testing for Visual Changes](#snapshot-testing-for-visual-changes)\n - [How to Update Snapshots](#how-to-update-snapshots)\n\n## Code of Conduct\n\nHelp us keep **KoliBri** open and inclusive. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n## Questions and problems\n\nPlease do not create issue tickets for general support questions. We want to use the ticket system for tracking bug reports and feature requests.\n\nInstead, we recommend first checking [Stack Overflow](https://stackoverflow.com/questions/tagged/kolibri) to see whether someone else has already solved the question or problem. You can also create new questions with the tag “hummingbird”.\nTo save your time and ours, we will close all general questions in the ticket system and redirect those asking to Stack Overflow.\n\nIf you would like to contact us, please send us an email to [kolibri@itzbund.de](mailto:kolibri@itzbund.de).\n\n## Report an error\n\nIf you find an error in the source code, you can report it to our ticket system.\n\nIt would be even better if you suggested a solution to us as a pull request.\n\n## Further development\n\nYou can request new features by submitting an issue to our ticket system. If you would like to implement a new function, please note the following steps for further action:\n\n- It is helpful to read the KoliBri [architecture concept](https://public-ui.github.io/docs/concepts/architecture) before implementing.\n- For major innovations, please create a ticket with the description of the new function.\n- For small innovations, you can offer and justify the implementation directly as a pull request.\n\nAlso see our guides, recommendations and HowTos here [Docs](./docs)\n\n### Git flow\n\nWe work according to the Git flow: https://medium.com/android-news/gitflow-with-github-c675aa4f606a\n\n### Pull Request Guidelines\n\nWhen creating a pull request, please follow these guidelines:\n\n- **PR Title:** The pull request title must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This is enforced by automated validation in our CI pipeline.\n- **PR Title Format:** `<type>: <description>` or `<type>(<scope>): <description>`\n- **Allowed Types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`\n- **Description:** The description must start with a letter (lowercase or uppercase) and clearly explain the change.\n\n**Examples of valid PR titles:**\n\n- `feat: add new button component`\n- `fix: resolve navigation issue on mobile devices`\n- `docs: update installation instructions`\n- `refactor(components): simplify input validation logic`\n- `test(visual-tests): Axe-Verstöße wieder als Build-Breaker auswerten`\n\n**Examples of invalid PR titles:**\n\n- `Add new feature` (missing type prefix)\n- `feat: 1st feature` (description must start with a letter)\n- `feature: add new button` (invalid type, should be `feat`)\n\n### Developing\n\n1. For contributing, you need a [GitHub account](https://github.com/login)\n2. Fork [our repository](https://github.com/public-ui/kolibri) on GitHub\n3. Open your preferred command line interface\n4. Clone the forked repository via HTTPS to your local machine. The VS Code GitHub extension can handle authentication.\n5. Navigate the project root directory\n6. Create a new branch for your changes\n7. Install Node.js version 22\n8. [Install PNPM](https://pnpm.io/installation) on you local machine\n9. Follow the [daily workflow](#daily-workflow) below\n\nRun ESLint across the repository with `pnpm lint` (or `pnpm lint:eslint` to invoke ESLint directly); the configuration lives in `packages/*/eslint.config.cjs`. Formatting is handled by Prettier via `pnpm format`, so run format first to keep ESLint focused on code-quality rules rather than style drift.\n\n### Daily workflow\n\nEvery package in the monorepo builds itself, and dependents always consume the built output of the\npackages they reference. The chain is kolicons → components → adapters → themes → sample →\npresentation. The order comes from the workspace dependencies: `pnpm -r build` builds every package\nexactly once, topologically sorted, and no package's build builds another package. No `dev` or\n`preview` script builds anything for you, so the workflow is always the same:\n\n```bash\ngit pull\npnpm i\npnpm -r build\n\n# One terminal per package you are changing\npnpm --filter @public-ui/components dev\npnpm --filter @public-ui/theme-default dev\n\n# The app to look at, http://localhost:9191\npnpm --filter @public-ui/presentation dev\n```\n\nThen work on the code: each watcher rebuilds its own package and the presentation app reloads.\n\n- A `dev` script exists in `@public-ui/components`, every theme package (`@public-ui/theme-bwst`,\n `-default`, `-desy`, `-ecl`, `-kern`) and `@public-ui/mcp`. Packages without one, such as the\n adapters or the icons, are rebuilt with `pnpm --filter <package> build` after a change.\n- Never run a build while a watcher is active. `pnpm -r build`, `pnpm build:deps` and the\n components `build` start with `pnpm clear` and delete the output the watcher owns. Stop the\n watchers, build, then start `dev` again.\n\n### VS Code Setup\n\nWe recommend using [Visual Studio Code](https://code.visualstudio.com/):\n\n- Install the Prettier and ESLint extensions.\n- Enable \"Format on Save\" in your settings.\n\n### Tests\n\nAll tests run via GitHub Actions when you open a pull request. Monitor them under the **Actions** tab.\n\n#### E2E tests (Playwright)\n\nThe Playwright tests of the components live next to the components as `*.e2e.ts` files (e.g. `packages/components/src/components/badge/badge.e2e.ts`). Run a single file or test from `packages/components`; the arguments are passed on to `playwright test`:\n\n```bash\ncd packages/components\n\npnpm test:e2e src/components/badge/badge.e2e.ts # one file\npnpm test:e2e src/components/badge/badge.e2e.ts -g \"title\" # one test by (part of) its title\npnpm test:e2e src/components/badge/badge.e2e.ts:42 # one test by line number\n```\n\nUseful flags: `--headed` (visible browser), `--ui` (Playwright UI mode), `--debug` (inspector). After a run, `pnpm exec playwright show-report` opens the HTML report.\n\n### Develop new component\n\nRefer to [new component](docs/tutorials/NEW_COMPONENT.md) tutorial.\n\n### Switching between branches\n\nAfter a branch switch, dependencies and build output may no longer match the code. Stop all\nwatchers and repeat the [daily workflow](#daily-workflow) from `pnpm i` on: reinstall, build\neverything, then start `dev` in the packages you are working on.\n\n### Back porting to older Major-Versions\n\nBy default, development is carried out in the `development` branch for the following version. However, if it becomes necessary to provide an issue for an older major release, such as version 1.x.x, the code change must also be merged into the corresponding release branch. In this case, it would be the `release/1` branch. It is important that the branch that was created from the `develop` is not merged into the release branch, as otherwise the next patch version will receive all the changes from the current development status.\nThe simplest procedure is therefore to create a new branch from the release branch (e.g. `release/1`) and transfer the individual commits of the feature branch from the `develop` to the new branch using cherry-picking. This branch can then be merged into the release branch as normal with a new pull request.\n\n### Visual Review for Visual Changes\n\nThe Continuous Integration (CI) pipeline takes screenshots of the React sample app in every theme and compares them with the baseline of the base branch. The screenshots are **not** stored in git: every push to `develop`, `main` and `release/*` publishes them as the artifact `visual-baseline-<package>`, and a pull request compares against the artifact of the commit it is merged with.\n\nWhen you introduce visual modifications to components, themes or the React sample app:\n\n1. The `visual-tests (<package>)` jobs report the differences. That is expected – there is nothing to regenerate or commit.\n2. The bot comment **📸 Visual Review** on the pull request links the review page (`https://public-ui.github.io/kolibri/visual/?pr=<number>`), where every changed, added and removed screenshot can be inspected side by side, with a slider, as onion skin or as diff.\n3. A reviewer with write access approves (or rejects) the screenshots there – directly with a fine-grained GitHub token, or by pasting the generated comment on the pull request, as a comment or as the text of a review. The commit status **Visual Review** turns green once everything is approved; approvals are bound to the screenshot content and survive later pushes that do not change the screenshot again.\n\nThe full process is described in [docs/visual-review.md](docs/visual-review.md).\n\n#### Running the visual tests locally\n\n```bash\npnpm snapshots:pull # download the current develop baseline into the snapshot folders (needs `gh auth login`)\npnpm --filter @public-ui/theme-default test # compare; the result is written to packages/themes/default/visual-report/\npnpm test:update:docker default # regenerate a baseline locally in the pinned Playwright container\n```\n\nScreenshots are platform specific (font rendering), so only the Docker variant produces files that match the CI.\n\n#### Text snapshots of the unit tests\n\nThe `__snapshots__` files of the unit tests (components, hydrate, hydrate-server) stay in git. Update them with `pnpm test:update:unit`, or run the `03 - Update Snapshots` action on your branch:\n\n```bash\ngh workflow run update-snapshots.yml -r `git rev-parse --abbrev-ref HEAD`\n```\n",
383
383
  "kind": "doc"
384
384
  },
385
385
  {
@@ -387,7 +387,7 @@
387
387
  "group": "docs",
388
388
  "name": "CVE_OVERVIEW",
389
389
  "path": "docs/CVE_OVERVIEW.md",
390
- "code": "# CVE Overview\n\n> For more security information, see [SECURITY.md](./SECURITY.md)\n\n## 1. Production Dependencies\n\n### Summary\n\n| Severity | v4 | v3 | v2 | v1 |\n| -------- | --: | --: | --: | --: |\n| critical | 0 | 0 | 0 | 0 |\n| high | 10 | 20 | 2 | 22 |\n| moderate | 2 | 16 | 2 | 7 |\n| low | 0 | 2 | 0 | 1 |\n| info | 0 | 0 | 0 | 0 |\n| unknown | 0 | 0 | 0 | 0 |\n\n### Vulnerabilities\n\n| Package | Severity | CVE | Affected Versions | Description |\n| ----------------------- | -------- | ------------------- | ----------------- | -------------------------------------------------------------------------------- |\n| @angular/common | high | CVE-2026-68945 | v3 | Angular: Cache-Key Ambiguity in HttpTransferCache Leading to Cross-Request Respo |\n| @angular/compiler | high | CVE-2026-69151 | v3 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/core | high | CVE-2026-69151 | v3 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| brace-expansion | high | CVE-2026-13149 | v1 | brace-expansion: DoS via exponential-time expansion of consecutive non-expanding |\n| brace-expansion | high | CVE-2026-14257 | v1 | brace-expansion: DoS via unbounded expansion length causing an out-of-memory pro |\n| brace-expansion | high | CVE-2026-69152 | v1 | brace-expansion: DoS via unbounded intermediate arrays, bypassing the CVE-2026-1 |\n| browserslist | high | CVE-2026-73089 | v1 | Browserslist: Unbounded memory growth (no cache eviction) via distinct query res |\n| browserslist | high | CVE-2026-73088 | v1 | Browserslist: Uncaught crash / prototype write via untrusted browserslist-stats. |\n| extract-zip | high | CVE-2026-56876 | v1 | extract-zip unvalidated symlink path traversal |\n| fast-uri | high | CVE-2026-18446 | v3, v1 | fast-uri vulnerable to host confusion via backslash authority introducer |\n| fast-uri | high | CVE-2026-75931 | v4, v1 | fast-uri vulnerable to host confusion via skipped IDN canonicalization on scheme |\n| fast-uri | high | CVE-2026-75975 | v4, v3, v1 | fast-uri vulnerable to server-side request forgery via malformed IPv6 normalizat |\n| fast-uri | high | CVE-2026-75899 | v4, v3, v1 | fast-uri vulnerable to server-side request forgery via repeated hostname percent |\n| fast-uri | high | CVE-2026-76172 | v4, v3, v1 | fast-uri vulnerable to host confusion via percent-encoded scheme normalization |\n| fast-uri | high | CVE-2026-16221 | v3 | fast-uri vulnerable to host confusion via literal backslash authority delimiter |\n| fast-uri | high | CVE-2026-13676 | v3 | fast-uri vulnerable to host confusion via failed IDN canonicalization |\n| find-my-way | high | CVE-2026-47219 | v3 | find-my-way: DDoS with HTTP2 |\n| image-size | high | CVE-2025-71330 | v4, v3, v2, v1 | image-size: ICNS parser allows denial of service through an infinite loop |\n| image-size | high | CVE-2025-71329 | v4, v3, v2, v1 | image-size: JXL and HEIF parsers allow denial of service through infinite loops |\n| immutable | high | CVE-2026-59879 | v3, v1 | Immutable.js `List` 32-bit trie overflow → unrecoverable DoS |\n| immutable | high | CVE-2026-59880 | v3, v1 | Immutable: Hash-collision algorithmic complexity denial of service in Immutable. |\n| ip-address | high | CVE-2026-69192 | v3 | ip-address: Address4 decodes leading-zero octets as decimal while resolvers deco |\n| js-yaml | high | GHSA-5p4m-2wfm-xmqj | v1 | JS-YAML: Quadratic CPU consumption in !!omap resolution (3.x and 4.x) — CVE-2026 |\n| linkify-it | high | CVE-2026-59887 | v3 | linkify-it: Quadratic-complexity DoS via the `mailto:` validator scan-loop on at |\n| lodash.pick | high | CVE-2020-8203 | v1 | Prototype Pollution in lodash |\n| minimatch | high | CVE-2026-27903 | v1 | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja |\n| minimatch | high | CVE-2026-27904 | v1 | minimatch ReDoS: nested *() extglobs generate catastrophically backtracking regu |\n| nanoid | high | CVE-2026-67213 | v3, v1 | nanoid: custom generators can loop indefinitely when size is zero |\n| nanoid | high | CVE-2026-67214 | v3 | nanoid: non-secure generators can loop indefinitely with negative size |\n| postcss | high | CVE-2026-73646 | v3 | PostCSS: Path Traversal in Previous Source Map Auto-Loading (sourceMappingURL) l |\n| react-router | high | GHSA-qwww-vcr4-c8h2 | v3 | React Router: RSC Mode CSRF Bypass Allows Action Execution Before 400 Response |\n| serialize-javascript | high | GHSA-5c6j-r48x-rmvq | v1 | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to |\n| @hono/node-server | moderate | GHSA-frvp-7c67-39w9 | v3 | Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encode |\n| brace-expansion | moderate | CVE-2026-45149 | v1 | brace-expansion: Large numeric range defeats documented `max` DoS protection |\n| dompurify | moderate | GHSA-55q2-fjhq-7xh7 | v1 | DOMPurify: IN_PLACE hook removal leaves a detached subtree executable, causing X |\n| fastify | moderate | CVE-2026-18504 | v3 | fastify vulnerable to schema validation bypass via root primitive coercion misma |\n| fastify | moderate | CVE-2026-16732 | v3 | fastify vulnerable to X-Forwarded-* spoofing under trustProxy hop-count |\n| hono | moderate | CVE-2026-59897 | v3 | Hono: API Gateway v1 adapter can drop a distinct repeated request header value d |\n| hono | moderate | CVE-2026-59896 | v3 | hono/jsx does not isolate context per request, leading to cross-request data dis |\n| hono | moderate | CVE-2026-59895 | v3 | Hono: Server-Side XSS via JSX Escaping Bypass in cx() Utility |\n| hono | moderate | CVE-2026-69207 | v3 | Hono: ReDoS in CORS middleware via Access-Control-Request-Headers |\n| hono | moderate | CVE-2026-71850 | v3 | Hono: `memo()` retains SSR output across requests, leading to cross-user data di |\n| hono | moderate | CVE-2026-71848 | v3 | Hono: Algorithmic Complexity DoS in Language Middleware |\n| ip-address | moderate | CVE-2026-69198 | v3 | ip-address: a CIDR suffix on the parsed address suppresses special-use classific |\n| ip-address | moderate | CVE-2026-54272 | v3 | ip-address: misclassification of IPv4-mapped/NAT64 IPv6 addresses can bypass SSR |\n| postcss | moderate | CVE-2026-69153 | v3 | PostCSS: incomplete fix of GHSA-6g55-p6wh-862q — attacker-controlled sourceMappi |\n| protobufjs | moderate | CVE-2026-59876 | v3 | protobufjs: Text Format string map parsing can mutate returned map object protot |\n| protobufjs | moderate | CVE-2026-59877 | v3 | protobufjs: Denial of Service via infinite loop in .proto option parsing |\n| qs | moderate | CVE-2026-8723 | v1 | qs has a remotely triggerable DoS: qs.stringify crashes with TypeError on null/u |\n| qs | moderate | CVE-2026-82562 | v4, v3, v2, v1 | qs array-limit bypass via bracket-key comma parsing |\n| qs | moderate | CVE-2026-82417 | v4, v3, v2, v1 | qs: Denial of Service via Attacker Controlled isBuffer |\n| react-router-dom | moderate | CVE-2026-53668 | v1 | React Router: Open redirect leading to XSS |\n| serialize-javascript | moderate | CVE-2026-34043 | v1 | Serialize JavaScript has CPU Exhaustion Denial of Service via crafted array-like |\n| body-parser | low | CVE-2026-12590 | v3 | body-parser vulnerable to denial of service when invalid limit value silently di |\n| hono | low | CVE-2026-71849 | v3 | Hono: Proxy Helper does not remove response headers listed in the `Connection` h |\n| postcss-selector-parser | low | CVE-2026-9358 | v1 | postcss-selector-parser allows denial of service through uncontrolled AST recurs |\n\n## 2. All Dependencies\n\n### Summary\n\n| Severity | v4 | v3 | v2 | v1 |\n| -------- | --: | --: | --: | --: |\n| critical | 1 | 9 | 4 | 5 |\n| high | 29 | 113 | 87 | 65 |\n| moderate | 19 | 80 | 68 | 26 |\n| low | 2 | 15 | 15 | 5 |\n| info | 0 | 0 | 0 | 0 |\n| unknown | 0 | 0 | 0 | 0 |\n\n### Vulnerabilities\n\n| Package | Severity | CVE | Affected Versions | Description |\n| ----------------------- | -------- | ------------------- | ----------------- | -------------------------------------------------------------------------------- |\n| basic-ftp | critical | CVE-2026-27699 | v3 | Basic FTP has Path Traversal Vulnerability in its downloadToDir() method |\n| fast-xml-parser | critical | CVE-2026-25896 | v3, v2 | fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE ent |\n| handlebars | critical | CVE-2026-33937 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion |\n| happy-dom | critical | CVE-2025-61927 | v4 | Happy DOM: VM Context Escape can lead to Remote Code Execution |\n| locutus | critical | CVE-2026-25521 | v3, v1 | locutus is vulnerable to Prototype Pollution |\n| locutus | critical | CVE-2026-32304 | v3, v2, v1 | Locutus vulnerable to RCE via unsanitized input in create_function() |\n| seroval | critical | CVE-2026-59940 | v3, v2, v1 | seroval: `seroval.fromJSON()` Promise resolver type confusion invokes attacker-c |\n| shell-quote | critical | CVE-2026-9277 | v3 | shell-quote quote() does not escape newlines in object .op values |\n| tar | critical | CVE-2026-59873 | v3, v1 | node-tar: Decompression/parse DoS via unlimited input |\n| websocket-driver | critical | CVE-2026-54466 | v3, v2 | websocket-driver: Message corruption via abuse of protocol length headers |\n| @angular/common | high | CVE-2025-66035 | v1 | Angular is Vulnerable to XSRF Token Leakage via Protocol-Relative URLs in Angula |\n| @angular/common | high | CVE-2026-54268 | v4, v3, v2, v1 | @angular/common: Denial of Service (DoS) via OOM in Date Formatting (formatDate) |\n| @angular/common | high | CVE-2026-54266 | v4, v3, v2, v1 | @angular/common: Weak 32-Bit Cache Key Hashing in `HttpTransferCache` Leading to |\n| @angular/common | high | CVE-2026-50171 | v1 | @angular/common: Denial of Service (DoS) via OOM in Number Formatting (digitsInf |\n| @angular/common | high | CVE-2026-50170 | v1 | @angular/common: Information Leak via Default Caching of Credentialed Requests i |\n| @angular/common | high | CVE-2026-68945 | v4, v3, v2, v1 | Angular: Cache-Key Ambiguity in HttpTransferCache Leading to Cross-Request Respo |\n| @angular/compiler | high | CVE-2026-32635 | v1 | Angular vulnerable to XSS in i18n attribute bindings |\n| @angular/compiler | high | CVE-2026-22610 | v1 | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes |\n| @angular/compiler | high | CVE-2025-66412 | v1 | Angular Stored XSS Vulnerability via SVG Animation, SVG URL and MathML Attribute |\n| @angular/compiler | high | CVE-2026-69151 | v4, v3, v2, v1 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/core | high | CVE-2026-27970 | v1 | Angular i18n vulnerable to Cross-Site Scripting |\n| @angular/core | high | CVE-2026-32635 | v1 | Angular vulnerable to XSS in i18n attribute bindings |\n| @angular/core | high | CVE-2026-22610 | v1 | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes |\n| @angular/core | high | CVE-2026-54267 | v4, v3, v2, v1 | Angular Client Hydration DOM Clobbering & Response-Cache Poisoning |\n| @angular/core | high | CVE-2026-69151 | v4, v3, v2, v1 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @hono/node-server | high | CVE-2026-29087 | v2 | @hono/node-server has authorization bypass for protected static paths via encode |\n| axios | high | CVE-2026-42043 | v3 | Axios: Incomplete Fix for CVE-2025-62718 — NO_PROXY Protection Bypassed via RFC |\n| axios | high | CVE-2026-42033 | v3 | Axios: Prototype Pollution Gadgets - Response Tampering, Data Exfiltration, and |\n| axios | high | CVE-2026-42035 | v3 | Axios: Header Injection via Prototype Pollution |\n| axios | high | CVE-2026-25639 | v3 | Axios is Vulnerable to Denial of Service via **proto** Key in mergeConfig |\n| axios | high | CVE-2026-42264 | v3 | Axios has prototype pollution read-side gadgets in HTTP adapter that allow crede |\n| axios | high | CVE-2026-44496 | v3 | Axios: Regular Expression Denial of Service (ReDoS) via Cookie Name Injection |\n| axios | high | CVE-2026-44488 | v3 | Allocation of Resources Without Limits or Throttling in Axios |\n| axios | high | CVE-2026-44487 | v3 | Axios: Proxy-Authorization Credential Leak to Origin Server Across HTTP-to-HTTPS |\n| axios | high | CVE-2026-44486 | v3 | Axios: Proxy-Authorization header leaks to redirect target when proxy is re-eval |\n| axios | high | CVE-2026-44495 | v3 | axios Vulnerable to Credential Theft and Response Hijacking via Prototype Pollut |\n| axios | high | CVE-2026-44494 | v3 | axios Vulnerable to Full Man-in-the-Middle via Prototype Pollution Gadget in `co |\n| basic-ftp | high | GHSA-6v7q-wjvx-w8wg | v3 | basic-ftp: Incomplete CRLF Injection Protection Allows Arbitrary FTP Command Exe |\n| basic-ftp | high | CVE-2026-41324 | v3 | basic-ftp vulnerable to denial of service via unbounded memory consumption in Cl |\n| basic-ftp | high | CVE-2026-44240 | v3 | basic-ftp allows a malicious FTP server to cause client-side denial of service v |\n| brace-expansion | high | CVE-2026-13149 | v3, v2, v1 | brace-expansion: DoS via exponential-time expansion of consecutive non-expanding |\n| brace-expansion | high | CVE-2026-14257 | v3, v2, v1 | brace-expansion: DoS via unbounded expansion length causing an out-of-memory pro |\n| brace-expansion | high | CVE-2026-69152 | v3, v2, v1 | brace-expansion: DoS via unbounded intermediate arrays, bypassing the CVE-2026-1 |\n| braces | high | CVE-2024-4068 | v3, v2, v1 | Uncontrolled resource consumption in braces |\n| browserslist | high | CVE-2026-73089 | v3, v2, v1 | Browserslist: Unbounded memory growth (no cache eviction) via distinct query res |\n| browserslist | high | CVE-2026-73088 | v3, v2, v1 | Browserslist: Uncaught crash / prototype write via untrusted browserslist-stats. |\n| deepmerge-ts | high | CVE-2026-40345 | v4, v3, v2 | DeepmergeTS has stack exhaustion when merging recursive object graphs |\n| engine.io | high | CVE-2026-59725 | v3, v2 | Socket.IO: Engine.IO Polling Transport Connection Exhaustion |\n| engine.io | high | CVE-2026-59724 | v3, v2 | Socket.IO: Engine.IO WebTransport SID DoS |\n| express-rate-limit | high | CVE-2026-30827 | v2 | express-rate-limit: IPv4-mapped IPv6 addresses bypass per-client rate limiting o |\n| extract-zip | high | CVE-2026-56876 | v4, v3, v2, v1 | extract-zip unvalidated symlink path traversal |\n| fast-uri | high | CVE-2026-18446 | v3, v2, v1 | fast-uri vulnerable to host confusion via backslash authority introducer |\n| fast-uri | high | CVE-2026-75931 | v4, v1 | fast-uri vulnerable to host confusion via skipped IDN canonicalization on scheme |\n| fast-uri | high | CVE-2026-75975 | v4, v3, v2, v1 | fast-uri vulnerable to server-side request forgery via malformed IPv6 normalizat |\n| fast-uri | high | CVE-2026-75899 | v4, v3, v1 | fast-uri vulnerable to server-side request forgery via repeated hostname percent |\n| fast-uri | high | CVE-2026-76172 | v4, v3, v2, v1 | fast-uri vulnerable to host confusion via percent-encoded scheme normalization |\n| fast-uri | high | CVE-2026-16221 | v3, v2 | fast-uri vulnerable to host confusion via literal backslash authority delimiter |\n| fast-uri | high | CVE-2026-6321 | v2 | fast-uri vulnerable to path traversal via percent-encoded dot segments |\n| fast-uri | high | CVE-2026-13676 | v3, v2 | fast-uri vulnerable to host confusion via failed IDN canonicalization |\n| fast-uri | high | CVE-2026-6322 | v2 | fast-uri vulnerable to host confusion via percent-encoded authority delimiters |\n| fast-xml-parser | high | CVE-2026-25128 | v3, v2 | fast-xml-parser has RangeError DoS Numeric Entities Bug |\n| fast-xml-parser | high | CVE-2026-26278 | v3, v2 | fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansio |\n| fast-xml-parser | high | CVE-2026-33036 | v3, v2 | fast-xml-parser affected by numeric entity expansion bypassing all entity expans |\n| find-my-way | high | CVE-2026-47219 | v3 | find-my-way: DDoS with HTTP2 |\n| flatted | high | CVE-2026-32141 | v3, v2 | flatted vulnerable to unbounded recursion DoS in parse() revive phase |\n| flatted | high | CVE-2026-33228 | v3, v2 | Prototype Pollution via parse() in NodeJS flatted |\n| form-data | high | CVE-2026-12143 | v3, v2, v1 | form-data: CRLF injection in form-data via unescaped multipart field names and f |\n| handlebars | high | CVE-2026-33938 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion by tampering @part |\n| handlebars | high | CVE-2026-33940 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion when passing an ob |\n| handlebars | high | CVE-2026-33939 | v3, v1 | Handlebars.js has Denial of Service via Malformed Decorator Syntax in Template C |\n| handlebars | high | CVE-2026-33941 | v3, v1 | Handlebars.js has JavaScript Injection in CLI Precompiler via Unescaped Names an |\n| happy-dom | high | CVE-2026-34226 | v4 | Happy DOM's fetch credentials include uses page-origin cookies instead of target |\n| happy-dom | high | CVE-2026-33943 | v4 | Happy DOM ECMAScriptModuleCompiler: unsanitized export names are interpolated as |\n| hono | high | CVE-2026-29045 | v2 | Hono vulnerable to arbitrary file access via serveStatic vulnerability |\n| hono | high | CVE-2026-54290 | v2 | hono: CORS Middleware reflects any Origin with credentials when `origin` default |\n| http-proxy-middleware | high | CVE-2026-55603 | v3 | http-proxy-middleware: multipart/form-data field injection via unescaped CRLF in |\n| image-size | high | CVE-2025-71330 | v4, v3, v2, v1 | image-size: ICNS parser allows denial of service through an infinite loop |\n| image-size | high | CVE-2025-71329 | v4, v3, v2, v1 | image-size: JXL and HEIF parsers allow denial of service through infinite loops |\n| immutable | high | CVE-2026-59879 | v3, v2, v1 | Immutable.js `List` 32-bit trie overflow → unrecoverable DoS |\n| immutable | high | CVE-2026-59880 | v3, v2, v1 | Immutable: Hash-collision algorithmic complexity denial of service in Immutable. |\n| immutable | high | CVE-2026-29063 | v2 | Immutable is vulnerable to Prototype Pollution |\n| ip-address | high | CVE-2026-69192 | v3, v2 | ip-address: Address4 decodes leading-zero octets as decimal while resolvers deco |\n| js-yaml | high | GHSA-5p4m-2wfm-xmqj | v3, v2, v1 | JS-YAML: Quadratic CPU consumption in !!omap resolution (3.x and 4.x) — CVE-2026 |\n| js-yaml | high | CVE-2026-59869 | v3, v2 | js-yaml: YAML merge-key chains can force quadratic CPU consumption |\n| linkify-it | high | CVE-2026-59887 | v3 | linkify-it: Quadratic-complexity DoS via the `mailto:` validator scan-loop on at |\n| locutus | high | CVE-2026-29091 | v3, v2, v1 | locutus call_user_func_array vulnerable to Remote Code Execution (RCE) due to Co |\n| lodash | high | CVE-2026-4800 | v3 | lodash vulnerable to Code Injection via `_.template` imports key names |\n| lodash.pick | high | CVE-2020-8203 | v2, v1 | Prototype Pollution in lodash |\n| minimatch | high | CVE-2026-27903 | v3, v2, v1 | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja |\n| minimatch | high | CVE-2026-27904 | v3, v2, v1 | minimatch ReDoS: nested *() extglobs generate catastrophically backtracking regu |\n| minimatch | high | CVE-2026-26996 | v3, v2 | minimatch has a ReDoS via repeated wildcards with non-matching literal in patter |\n| nanoid | high | CVE-2026-67213 | v3, v1 | nanoid: custom generators can loop indefinitely when size is zero |\n| nanoid | high | CVE-2026-67214 | v3 | nanoid: non-secure generators can loop indefinitely with negative size |\n| nanoid | high | CVE-2026-73086 | v3 | nanoid: Integer Overflow or Wraparound |\n| node-forge | high | CVE-2026-33896 | v2 | Forge has a basicConstraints bypass in its certificate chain verification (RFC 5 |\n| node-forge | high | CVE-2026-33895 | v2 | Forge has signature forgery in Ed25519 due to missing S > L check |\n| node-forge | high | CVE-2026-33891 | v2 | Forge has Denial of Service via Infinite Loop in BigInteger.modInverse() with Ze |\n| node-forge | high | CVE-2026-33894 | v2 | Forge has signature forgery in RSA-PKCS due to ASN.1 extra field |\n| nx | high | CVE-2026-71476 | v3, v1 | Nx: Zip-Slip in the self-hosted remote cache |\n| pacote | high | CVE-2026-9496 | v3, v2, v1 | pacote is vulnerable to Denial of Service (DoS) via the addGitSha function |\n| path-to-regexp | high | CVE-2026-4867 | v3, v2 | path-to-regexp vulnerable to Regular Expression Denial of Service via multiple r |\n| path-to-regexp | high | CVE-2026-4926 | v2 | path-to-regexp vulnerable to Denial of Service via sequential optional groups |\n| piscina | high | CVE-2026-55388 | v3 | piscina: Prototype Pollution Gadget → RCE via inherited options.filename |\n| postcss | high | CVE-2026-45623 | v4, v3, v2 | PostCSS: Arbitrary file read and information disclosure via attacker-controlled |\n| postcss | high | CVE-2026-73646 | v4, v3, v2 | PostCSS: Path Traversal in Previous Source Map Auto-Loading (sourceMappingURL) l |\n| react-router | high | GHSA-qwww-vcr4-c8h2 | v3 | React Router: RSC Mode CSRF Bypass Allows Action Execution Before 400 Response |\n| rollup | high | CVE-2026-27606 | v1 | Rollup 4 has Arbitrary File Write via Path Traversal |\n| semver | high | CVE-2022-25883 | v2 | semver vulnerable to Regular Expression Denial of Service |\n| serialize-javascript | high | GHSA-5c6j-r48x-rmvq | v4, v3, v2, v1 | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to |\n| shell-quote | high | CVE-2026-13311 | v3 | shell-quote: Quadratic-complexity Denial of Service in `parse()` (CWE-407) |\n| sigstore | high | CVE-2026-48815 | v3, v2, v1 | sigstore's `certificateOIDs` verification constraints are silently dropped and n |\n| socket.io-parser | high | CVE-2026-33151 | v3, v2 | socket.io allows an unbounded number of binary attachments |\n| socket.io-parser | high | CVE-2026-69185 | v3, v2 | Socket.IO: Zero-attachment Memory Exhaustion |\n| svgo | high | CVE-2026-29074 | v3, v2, v1 | SVGO DoS through entity expansion in DOCTYPE (Billion Laughs) |\n| svgo | high | CVE-2026-73650 | v3, v2, v1 | SVGO removeScripts plugin leaves some executable scripts intact |\n| tar | high | CVE-2026-24842 | v1 | node-tar Vulnerable to Arbitrary File Creation/Overwrite via Hardlink Path Trave |\n| tar | high | CVE-2026-23745 | v1 | node-tar is Vulnerable to Arbitrary File Overwrite and Symlink Poisoning via Ins |\n| tar | high | CVE-2026-26960 | v1 | Arbitrary File Read/Write via Hardlink Target Escape Through Symlink Chain in no |\n| tar | high | CVE-2026-29786 | v1 | tar has Hardlink Path Traversal via Drive-Relative Linkpath |\n| tar | high | CVE-2026-31802 | v1 | node-tar Symlink Path Traversal via Drive-Relative Linkpath |\n| tar | high | CVE-2026-23950 | v1 | Race Condition in node-tar Path Reservations via Unicode Ligature Collisions on |\n| tar | high | CVE-2026-59874 | v3, v1 | node-tar: Negative tar entry size causes infinite loop in archive replace |\n| tar | high | CVE-2026-73566 | v3, v2, v1 | node-tar: Uncontrolled recursion in mapHas/filesFilter allows uncatchable stack- |\n| tmp | high | CVE-2026-44705 | v3, v2 | tmp has Path Traversal via unsanitized prefix/postfix that enables directory esc |\n| undici | high | CVE-2026-1528 | v3 | Undici: Malicious WebSocket 64-bit length overflows parser and crashes the clien |\n| undici | high | CVE-2026-1526 | v3 | Undici has Unbounded Memory Consumption in WebSocket permessage-deflate Decompre |\n| undici | high | CVE-2026-2229 | v3 | Undici has Unhandled Exception in WebSocket Client Due to Invalid server_max_win |\n| undici | high | CVE-2026-9697 | v3 | undici vulnerable to TLS certificate validation bypass via dropped requestTls in |\n| undici | high | CVE-2026-12151 | v3 | undici WebSocket client vulnerable to denial of service via fragment count bypas |\n| undici | high | CVE-2026-6734 | v3 | undici vulnerable to cross-origin request routing via SOCKS5 proxy pool reuse |\n| undici | high | CVE-2026-13697 | v3 | undici vulnerable to cross-user information disclosure and parse-time crash via |\n| vite | high | CVE-2026-39364 | v1 | Vite: `server.fs.deny` bypassed with queries |\n| vite | high | CVE-2026-39363 | v1 | Vite Vulnerable to Arbitrary File Read via Vite Dev Server WebSocket |\n| vite | high | CVE-2026-53571 | v3, v1 | vite: `server.fs.deny` bypass on Windows alternate paths |\n| ws | high | CVE-2026-48779 | v3, v2, v1 | ws: Memory exhaustion DoS from tiny fragments and data chunks |\n| @angular/compiler | moderate | CVE-2026-54265 | v4, v3, v2, v1 | @angular/compiler: Two-Way Property Binding Sanitization Bypass (XSS) |\n| @angular/compiler | moderate | CVE-2026-50557 | v4, v1 | Angular: Template and Attribute Namespace Sanitization Bypass (XSS) |\n| @angular/core | moderate | CVE-2026-50557 | v4, v1 | Angular: Template and Attribute Namespace Sanitization Bypass (XSS) |\n| @angular/core | moderate | CVE-2026-52725 | v4, v1 | @angular/core: Angular Template and Dynamic Component Namespace Bypass leading t |\n| @hono/node-server | moderate | CVE-2026-39406 | v2 | @hono/node-server: Middleware bypass via repeated slashes in serveStatic |\n| @hono/node-server | moderate | GHSA-frvp-7c67-39w9 | v3, v2 | Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encode |\n| @humanfs/node | moderate | GHSA-p498-v437-472g | v3 | humanfs: Recursive copy follows symlinked files and copies data from outside the |\n| @opentelemetry/core | moderate | CVE-2026-54285 | v1 | OpenTelemetry Core: Unbounded memory allocation in W3C Baggage propagation |\n| @sigstore/core | moderate | CVE-2026-48758 | v3, v2, v1 | @sigstore/core has DSSE payloadType type-binding failure |\n| @xmldom/xmldom | moderate | CVE-2026-83610 | v4 | xmldom: XML fragment injection via invalid EntityReference.nodeName during requi |\n| ajv | moderate | CVE-2025-69873 | v3, v2 | ajv has ReDoS when using `$data` option |\n| axios | moderate | CVE-2025-62718 | v3 | Axios has a NO_PROXY Hostname Normalization Bypass that Leads to SSRF |\n| axios | moderate | CVE-2026-42041 | v3 | Axios: Authentication Bypass via Prototype Pollution Gadget in `validateStatus` |\n| axios | moderate | CVE-2026-42044 | v3 | Axios: Invisible JSON Response Tampering via Prototype Pollution Gadget in `pars |\n| axios | moderate | CVE-2026-42037 | v3 | Axios: CRLF Injection in multipart/form-data body via unsanitized blob.type in f |\n| axios | moderate | CVE-2026-42038 | v3 | Axios: no_proxy bypass via IP alias allows SSRF |\n| axios | moderate | CVE-2026-42034 | v3 | Axios' HTTP adapter-streamed uploads bypass maxBodyLength when maxRedirects: 0 |\n| axios | moderate | CVE-2026-42036 | v3 | Axios: HTTP adapter streamed responses bypass maxContentLength |\n| axios | moderate | CVE-2026-42042 | v3 | Axios: XSRF Token Cross-Origin Leakage via Prototype Pollution Gadget in `withXS |\n| axios | moderate | CVE-2026-40175 | v3 | Axios has Unrestricted Cloud Metadata Exfiltration via Header Injection Chain |\n| axios | moderate | CVE-2026-42039 | v3 | Axios: unbounded recursion in toFormData causes DoS via deeply nested request da |\n| axios | moderate | CVE-2026-44490 | v3 | axios has DoS & Header Injection via Prototype Pollution Read-Side Gadgets in ax |\n| axios | moderate | CVE-2026-67316 | v3 | Axios: Prototype pollution gadgets can alter axios request construction |\n| axios | moderate | CVE-2026-67312 | v3 | Axios: Deep formToJSON Key Recursion Can Cause Denial of Service |\n| axios | moderate | CVE-2026-67319 | v3 | Axios: Nested axios option objects can consume polluted prototype values |\n| axios | moderate | CVE-2026-67317 | v3 | Axios: Fetch adapter `ReadableStream` uploads bypass `maxBodyLength` |\n| axios | moderate | CVE-2026-67313 | v3 | Axios: Excessive recursion in formDataToJSON can cause denial of service |\n| brace-expansion | moderate | CVE-2026-45149 | v3, v2, v1 | brace-expansion: Large numeric range defeats documented `max` DoS protection |\n| brace-expansion | moderate | CVE-2026-33750 | v3, v2 | brace-expansion: Zero-step sequence causes process hang and memory exhaustion |\n| decode-uri-component | moderate | CVE-2026-45822 | v3, v2, v1 | decode-uri-component: Denial of service via exponential decoding of malformed pe |\n| dompurify | moderate | GHSA-55q2-fjhq-7xh7 | v1 | DOMPurify: IN_PLACE hook removal leaves a detached subtree executable, causing X |\n| ejs | moderate | CVE-2024-33883 | v2 | ejs lacks certain pollution protection |\n| esbuild | moderate | GHSA-67mh-4wv8-2f99 | v2 | esbuild enables any website to send any requests to the development server and r |\n| fast-xml-parser | moderate | CVE-2026-33349 | v3, v2 | Entity Expansion Limits Bypassed When Set to Zero Due to JavaScript Falsy Evalua |\n| fast-xml-parser | moderate | CVE-2026-41650 | v3, v2 | fast-xml-parser XMLBuilder: XML Comment and CDATA Injection via Unescaped Delimi |\n| fastify | moderate | CVE-2026-18504 | v3 | fastify vulnerable to schema validation bypass via root primitive coercion misma |\n| fastify | moderate | CVE-2026-16732 | v3 | fastify vulnerable to X-Forwarded-* spoofing under trustProxy hop-count |\n| file-type | moderate | CVE-2026-31808 | v4 | file-type affected by infinite loop in ASF parser on malformed input with zero-s |\n| handlebars | moderate | CVE-2026-33916 | v3, v1 | Handlebars.js has Prototype Pollution Leading to XSS through Partial Template In |\n| handlebars | moderate | GHSA-7rx3-28cr-v5wh | v3, v1 | Handlebars.js has a Prototype Method Access Control Gap via Missing __lookupSett |\n| hono | moderate | CVE-2026-29086 | v2 | Hono Vulnerable to Cookie Attribute Injection via Unsanitized domain and path in |\n| hono | moderate | CVE-2026-29085 | v2 | Hono Vulnerable to SSE Control Field Injection via CR/LF in writeSSE() |\n| hono | moderate | GHSA-v8w9-8mx6-g223 | v2 | Hono vulnerable to Prototype Pollution possible through **proto** key allowed in |\n| hono | moderate | GHSA-26pp-8wgv-hjvm | v2 | Hono missing validation of cookie name on write path in setCookie() |\n| hono | moderate | CVE-2026-39410 | v2 | Hono: Non-breaking space prefix bypass in cookie name handling in getCookie() |\n| hono | moderate | CVE-2026-39408 | v2 | Hono: Path traversal in toSSG() allows writing files outside the output director |\n| hono | moderate | CVE-2026-39407 | v2 | Hono: Middleware bypass via repeated slashes in serveStatic |\n| hono | moderate | CVE-2026-39409 | v2 | Hono has incorrect IP matching in ipRestriction() for IPv4-mapped IPv6 addresses |\n| hono | moderate | CVE-2026-44458 | v2 | Hono has CSS Declaration Injection via Style Object Values in JSX SSR |\n| hono | moderate | CVE-2026-44457 | v2 | Hono's Cache Middleware ignores Vary: Authorization / Vary: Cookie leading to cr |\n| hono | moderate | CVE-2026-44456 | v2 | Hono: bodyLimit() can be bypassed for chunked / unknown-length requests |\n| hono | moderate | CVE-2026-44455 | v2 | hono/jsx has Unvalidated JSX Tag Names that May Allow HTML Injection |\n| hono | moderate | CVE-2026-47674 | v2 | Hono: IP Restriction bypasses static deny rules for non-canonical IPv6 |\n| hono | moderate | CVE-2026-47675 | v2 | Hono: Cookie helper does not sanitize sameSite and priority, allowing Set-Cookie |\n| hono | moderate | CVE-2026-47673 | v2 | Hono: JWT middleware accepts any Authorization scheme, not only Bearer |\n| hono | moderate | CVE-2026-47676 | v2 | Hono: app.mount() strips mount prefix using undecoded path, causing incorrect ro |\n| hono | moderate | CVE-2026-56761 | v2 | hono Improperly Handles JSX Attribute Names Allows HTML Injection in hono/jsx SS |\n| hono | moderate | CVE-2026-54288 | v2 | hono: Body Limit Middleware can be bypassed on AWS Lambda by understating `Conte |\n| hono | moderate | CVE-2026-54289 | v2 | hono: Lambda@Edge adapter keeps only the last value of a repeated request header |\n| hono | moderate | CVE-2026-54286 | v2 | hono: Path traversal in `serve-static` on Windows via encoded backslash (`%5C`) |\n| hono | moderate | CVE-2026-54287 | v2 | hono: AWS Lambda adapter merges multiple `Set-Cookie` headers into one value, dr |\n| hono | moderate | CVE-2026-59897 | v3, v2 | Hono: API Gateway v1 adapter can drop a distinct repeated request header value d |\n| hono | moderate | CVE-2026-59895 | v3, v2 | Hono: Server-Side XSS via JSX Escaping Bypass in cx() Utility |\n| hono | moderate | CVE-2026-69207 | v3, v2 | Hono: ReDoS in CORS middleware via Access-Control-Request-Headers |\n| hono | moderate | CVE-2026-71850 | v3, v2 | Hono: `memo()` retains SSR output across requests, leading to cross-user data di |\n| hono | moderate | CVE-2026-59896 | v3 | hono/jsx does not isolate context per request, leading to cross-request data dis |\n| hono | moderate | CVE-2026-71848 | v3 | Hono: Algorithmic Complexity DoS in Language Middleware |\n| http-proxy-middleware | moderate | CVE-2026-55602 | v3, v2 | http-proxy-middleware `router` host+path substring matching allows Host-header-d |\n| ip-address | moderate | CVE-2026-42338 | v2 | ip-address has XSS in Address6 HTML-emitting methods |\n| ip-address | moderate | CVE-2026-69198 | v3 | ip-address: a CIDR suffix on the parsed address suppresses special-use classific |\n| ip-address | moderate | CVE-2026-54272 | v3 | ip-address: misclassification of IPv4-mapped/NAT64 IPv6 addresses can bypass SSR |\n| js-yaml | moderate | CVE-2025-64718 | v2 | js-yaml has prototype pollution in merge (<<) |\n| js-yaml | moderate | CVE-2026-53550 | v3, v2 | JS-YAML: Quadratic-complexity DoS in merge key handling via repeated aliases |\n| launch-editor | moderate | CVE-2026-53632 | v3, v2 | launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows |\n| locutus | moderate | CVE-2026-33993 | v3, v2, v1 | Locutus has Prototype Pollution via **proto** Key Injection in unserialize() |\n| locutus | moderate | CVE-2026-33994 | v2 | Locutus Prototype Pollution due to incomplete fix for CVE-2026-25521 |\n| lodash | moderate | CVE-2026-2950 | v3 | lodash vulnerable to Prototype Pollution via array path bypass in `_.unset` and |\n| micromatch | moderate | CVE-2024-4067 | v3, v2, v1 | Regular Expression Denial of Service (ReDoS) in micromatch |\n| nx | moderate | CVE-2026-54753 | v3, v1 | `nx graph` dev server permissive CORS policy |\n| path-to-regexp | moderate | CVE-2026-4923 | v2 | path-to-regexp vulnerable to Regular Expression Denial of Service via multiple w |\n| postcss | moderate | CVE-2026-41305 | v4, v3, v2 | PostCSS has XSS via Unescaped </style> in its CSS Stringify Output |\n| postcss | moderate | CVE-2026-69153 | v4, v3, v2 | PostCSS: incomplete fix of GHSA-6g55-p6wh-862q — attacker-controlled sourceMappi |\n| protobufjs | moderate | CVE-2026-59876 | v3 | protobufjs: Text Format string map parsing can mutate returned map object protot |\n| protobufjs | moderate | CVE-2026-59877 | v3 | protobufjs: Denial of Service via infinite loop in .proto option parsing |\n| qs | moderate | CVE-2026-8723 | v3, v2, v1 | qs has a remotely triggerable DoS: qs.stringify crashes with TypeError on null/u |\n| qs | moderate | CVE-2026-82562 | v4, v3, v2, v1 | qs array-limit bypass via bracket-key comma parsing |\n| qs | moderate | CVE-2026-82417 | v4, v3, v2, v1 | qs: Denial of Service via Attacker Controlled isBuffer |\n| qs | moderate | CVE-2025-15284 | v2 | qs's arrayLimit bypass in its bracket notation allows DoS via memory exhaustion |\n| react-router-dom | moderate | CVE-2026-53668 | v1 | React Router: Open redirect leading to XSS |\n| serialize-javascript | moderate | CVE-2026-34043 | v4, v3, v2, v1 | Serialize JavaScript has CPU Exhaustion Denial of Service via crafted array-like |\n| serialize-javascript | moderate | CVE-2024-11831 | v2 | Cross-site Scripting (XSS) in serialize-javascript |\n| smol-toml | moderate | GHSA-v3rj-xjv7-4jmq | v3, v1 | smol-toml: Denial of Service via TOML documents containing thousands of consecut |\n| tar | moderate | CVE-2026-53655 | v3, v1 | node-tar applies PAX size override to intermediary GNU long-name/long-link heade |\n| tar | moderate | CVE-2026-59871 | v3, v1 | node-tar: Process crash via PAX numeric path type confusion |\n| tar | moderate | CVE-2026-59875 | v3, v1 | node-tar: Uncaught Exception DoS via NUL byte in PAX path/linkpath records |\n| undici | moderate | CVE-2026-1525 | v3 | Undici has an HTTP Request/Response Smuggling issue |\n| undici | moderate | CVE-2026-1527 | v3 | Undici has CRLF Injection in undici via `upgrade` option |\n| undici | moderate | CVE-2026-9679 | v3 | undici vulnerable to HTTP header injection via Set-Cookie percent-decoding |\n| undici | moderate | CVE-2026-9678 | v3 | undici vulnerable to cross-user information disclosure via shared cache whitespa |\n| undici | moderate | CVE-2026-16728 | v3 | undici vulnerable to downstream response desynchronization via retry interceptor |\n| undici | moderate | CVE-2026-15157 | v3 | undici vulnerable to CRLF Injection via blob-like body 'type' property |\n| undici | moderate | CVE-2026-14643 | v3 | undici vulnerable to cross-user information disclosure via whitespace around equ |\n| undici | moderate | CVE-2026-16729 | v3 | undici vulnerable to cookie attribute injection via unsanitized domain and unpar |\n| uuid | moderate | CVE-2026-41907 | v4, v3, v2 | uuid: Missing buffer bounds check in v3/v5/v6 when buf is provided |\n| vite | moderate | CVE-2026-39365 | v1 | Vite Vulnerable to Path Traversal in Optimized Deps `.map` Handling |\n| vite | moderate | CVE-2026-53632 | v3, v1 | launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows |\n| webpack | moderate | CVE-2024-43788 | v2 | Webpack's AutoPublicPathRuntimeModule has a DOM Clobbering Gadget that leads to |\n| webpack-dev-server | moderate | CVE-2025-30360 | v2 | webpack-dev-server users' source code may be stolen when they access a malicious |\n| webpack-dev-server | moderate | CVE-2025-30359 | v2 | webpack-dev-server users' source code may be stolen when they access a malicious |\n| webpack-dev-server | moderate | CVE-2026-6402 | v2 | webpack-dev-server vulnerable to cross-origin source code exposure on non-HTTPS |\n| webpack-dev-server | moderate | CVE-2026-9595 | v2 | webpack-dev-server vulnerable to HMR WebSocket interception via permissive user |\n| webpack-dev-server | moderate | CVE-2026-14620 | v3, v2 | webpack-dev-server vulnerable to cross-site request forgery via internal develop |\n| webpack-dev-server | moderate | CVE-2026-14631 | v3, v2 | webpack-dev-server vulnerable to denial of service via a malformed Host or Origi |\n| websocket-driver | moderate | CVE-2026-54490 | v3, v2 | websocket-driver: Resource limit bypass via message compression |\n| ws | moderate | CVE-2026-45736 | v3, v2 | ws: Uninitialized memory disclosure |\n| yaml | moderate | CVE-2026-33532 | v3, v2, v1 | yaml is vulnerable to Stack Overflow via deeply nested YAML collections |\n| @babel/core | low | CVE-2026-49356 | v4, v3, v2, v1 | @babel/core: Arbitrary File Read via sourceMappingURL Comment |\n| @tootallnate/once | low | CVE-2026-3449 | v3, v2, v1 | @tootallnate/once vulnerable to Incorrect Control Flow Scoping |\n| axios | low | CVE-2026-42040 | v3 | Axios: Null Byte Injection via Reverse-Encoding in AxiosURLSearchParams |\n| body-parser | low | CVE-2026-12590 | v3, v2 | body-parser vulnerable to denial of service when invalid limit value silently di |\n| diff | low | CVE-2026-24001 | v4, v3, v2 | jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch |\n| fast-xml-parser | low | CVE-2026-27942 | v3, v2 | fast-xml-parser has stack overflow in XMLBuilder with preserveOrder |\n| handlebars | low | GHSA-442j-39wm-28r2 | v3, v1 | Handlebars.js has a Property Access Validation Bypass in container.lookup |\n| hono | low | GHSA-gq3j-xvxp-8hrf | v2 | Hono added timing comparison hardening in basicAuth and bearerAuth |\n| hono | low | CVE-2026-44459 | v2 | Hono has improper validation of NumericDate claims (exp, nbf, iat) in JWT verify |\n| hono | low | CVE-2026-71849 | v3, v2 | Hono: Proxy Helper does not remove response headers listed in the `Connection` h |\n| postcss-selector-parser | low | CVE-2026-9358 | v3, v2, v1 | postcss-selector-parser allows denial of service through uncontrolled AST recurs |\n| qs | low | CVE-2026-2391 | v2 | qs's arrayLimit bypass in comma parsing allows denial of service |\n| undici | low | CVE-2026-11525 | v3 | undici vulnerable to Set-Cookie SameSite attribute downgrade via permissive subs |\n| undici | low | CVE-2026-6733 | v3 | undici vulnerable to HTTP response queue poisoning via keep-alive socket reuse |\n| webpack | low | CVE-2025-68458 | v2 | webpack buildHttp: allowedUris allow-list bypass via URL userinfo (@) leading to |\n| webpack | low | CVE-2025-68157 | v2 | webpack buildHttp HttpUriPlugin allowedUris bypass via HTTP redirects → SSRF + c |\n",
390
+ "code": "# CVE Overview\n\n> For more security information, see [SECURITY.md](./SECURITY.md)\n\n## 1. Production Dependencies\n\n### Summary\n\n| Severity | v5 | v4 | v3 | v2 | v1 |\n| -------- | --: | --: | --: | --: | --: |\n| critical | 5 | 6 | 1 | 2 | 4 |\n| high | 21 | 21 | 41 | 14 | 49 |\n| moderate | 17 | 20 | 40 | 8 | 30 |\n| low | 5 | 5 | 8 | 3 | 8 |\n| info | 0 | 0 | 0 | 0 | 0 |\n| unknown | 0 | 0 | 0 | 0 | 0 |\n\n### Vulnerabilities\n\n| Package | Severity | CVE | Affected Versions | Description |\n| ------------------------- | -------- | ------------------- | ------------------ | -------------------------------------------------------------------------------- |\n| @simple-git/argv-parser | critical | CVE-2026-102829 | v5, v4 | simple-git: `VISUAL` editor environment variable is omitted from unsafe editor d |\n| dompurify | critical | GHSA-cg2g-xh64-v4q7 | v1 | DOMPurify SAFE_FOR_TEMPLATES bypass: split template expressions survive in attac |\n| handlebars | critical | CVE-2026-106446 | v5, v4 | Handlebars: JavaScript Injection via AST Type Confusion in compile (bypass of CV |\n| handlebars | critical | CVE-2026-106445 | v5, v4 | Handlebars: JavaScript Injection via Own Property Check Bypass |\n| proxy-addr | critical | CVE-2026-90711 | v4, v3, v1 | proxy-addr vulnerable to IP spoofing via IPv4-mapped IPv6 trust subnet |\n| seroval | critical | CVE-2026-104846 | v2, v1 | Seroval: `fromJSON()` Promise thenable assimilation invokes plugin-produced call |\n| shell-quote | critical | CVE-2026-102422 | v5, v4, v2, v1 | shell-quote: `quote()` command injection via a line terminator in a token after |\n| simple-git | critical | CVE-2026-102828 | v5, v4 | simple-git unsafe-operation guard does not block trailer command configuration |\n| @angular/common | high | CVE-2026-68945 | v3 | Angular: Cache-Key Ambiguity in HttpTransferCache Leading to Cross-Request Respo |\n| @angular/compiler | high | CVE-2026-69151 | v3 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/core | high | CVE-2026-69151 | v3 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/router | high | CVE-2026-101896 | v3, v2 | Angular Server-Side Rendering (SSR): Denial of Service via Numeric URL Matrix Pa |\n| @angular/router | high | CVE-2026-111752 | v3, v2 | @angular/router: Denial of Service via Unmatched Empty-Path Outlet Route Matchin |\n| @angular/router | high | CVE-2026-111751 | v3, v2 | @angular/router: Denial of Service via RouterLink Query Parameter Retention in S |\n| @grpc/grpc-js | high | CVE-2026-101916 | v3 | @grpc/grpc-js: In certain configurations, getAuthContext can return unauthorized |\n| @modelcontextprotocol/sdk | high | CVE-2026-104850 | v3 | MCP TypeScript SDK: OAuth client could send credentials to an authorization serv |\n| @modelcontextprotocol/sdk | high | CVE-2026-111767 | v3 | MCP TypeScript SDK: Experimental tasks were not tied to the session that created |\n| @modelcontextprotocol/sdk | high | CVE-2026-111768 | v3 | MCP TypeScript SDK: One HTTP request within the default size limit could exhaust |\n| @modelcontextprotocol/sdk | high | GHSA-f897-62hf-6gxq | v3 | MCP TypeScript SDK: HTTP server transports and handlers did not limit request bo |\n| axios | high | CVE-2026-101903 | v1 | Axios: ReDoS in fromDataURI data: URL parser freezes the Node event loop (DoS) |\n| axios | high | CVE-2026-101906 | v1 | Axios: ReDoS (O(N²)) in shouldBypassProxy host normalization, reachable via untr |\n| axios | high | CVE-2026-101909 | v1 | Axios: Prototype Pollution Gadget in axios toFormData Options |\n| axios | high | CVE-2026-101898 | v1 | Axios: HTTP/2 adapter bypasses configured DNS lookup and proxy controls |\n| axios | high | CVE-2026-101901 | v1 | Axios: Denial of Service via Unhandled 'error' Event in HTTP/2 ClientHttp2Sessio |\n| axios | high | CVE-2026-101905 | v1 | Axios: Node HTTP adapter prototype-pollution gadget allows request socket hijack |\n| axios | high | CVE-2026-101907 | v1 | Axios: maxRedirects: 0 is not enforced by the fetch adapter, allowing redirect-b |\n| basic-ftp | high | CVE-2026-102990 | v1 | basic-ftp: Quadratic-time CPU denial of service in Client.list() Unix directory- |\n| body-parser | high | CVE-2026-111181 | v5, v4, v3, v1 | body-parser vulnerable to Denial of Service via trailing bytes after a compresse |\n| brace-expansion | high | CVE-2026-13149 | v1 | brace-expansion: DoS via exponential-time expansion of consecutive non-expanding |\n| brace-expansion | high | CVE-2026-14257 | v1 | brace-expansion: DoS via unbounded expansion length causing an out-of-memory pro |\n| brace-expansion | high | CVE-2026-69152 | v1 | brace-expansion: DoS via unbounded intermediate arrays, bypassing the CVE-2026-1 |\n| brace-expansion | high | CVE-2026-102278 | v5, v4, v1 | brace-expansion: DoS via uncontrolled recursion on nested brace groups causing s |\n| brace-expansion | high | CVE-2026-102276 | v5, v4, v1 | brace-expansion: DoS via uncontrolled recursion in parseCommaParts causing stack |\n| browserslist | high | CVE-2026-73089 | v1 | Browserslist: Unbounded memory growth (no cache eviction) via distinct query res |\n| browserslist | high | CVE-2026-73088 | v1 | Browserslist: Uncaught crash / prototype write via untrusted browserslist-stats. |\n| compression | high | CVE-2026-87776 | v1 | compression vulnerable to Denial of Service via memory leak on premature respons |\n| dompurify | high | GHSA-mrv2-3pqr-j5jr | v1 | DOMPurify IN_PLACE: hook that removes a parent or sibling leaves the detached su |\n| extract-zip | high | CVE-2026-56876 | v1 | extract-zip unvalidated symlink path traversal |\n| extract-zip | high | CVE-2026-19693 | v1 | extract-zip allows arbitrary file writes through symlink archive entries |\n| fast-uri | high | CVE-2026-18446 | v3, v1 | fast-uri vulnerable to host confusion via backslash authority introducer |\n| fast-uri | high | CVE-2026-75931 | v5, v4, v1 | fast-uri vulnerable to host confusion via skipped IDN canonicalization on scheme |\n| fast-uri | high | CVE-2026-75975 | v5, v4, v3, v1 | fast-uri vulnerable to server-side request forgery via malformed IPv6 normalizat |\n| fast-uri | high | CVE-2026-75899 | v5, v4, v3, v1 | fast-uri vulnerable to server-side request forgery via repeated hostname percent |\n| fast-uri | high | CVE-2026-76172 | v5, v4, v3, v1 | fast-uri vulnerable to host confusion via percent-encoded scheme normalization |\n| fast-uri | high | CVE-2026-84292 | v5, v4, v3, v1 | fast-uri vulnerable to authority injection via an unvalidated port in serialize |\n| fast-uri | high | CVE-2026-16221 | v3 | fast-uri vulnerable to host confusion via literal backslash authority delimiter |\n| fast-uri | high | CVE-2026-13676 | v3 | fast-uri vulnerable to host confusion via failed IDN canonicalization |\n| fastify | high | CVE-2026-84504 | v3 | fastify vulnerable to request body replacement via an async validation result co |\n| fastify | high | CVE-2026-76169 | v3 | fastify vulnerable to authentication bypass via malformed URLs reaching encapsul |\n| fastify | high | CVE-2026-84469 | v3 | fastify vulnerable to request validation bypass via skipped boolean false schema |\n| fastify | high | CVE-2026-84428 | v3 | fastify vulnerable to header validation bypass via incomplete schema case normal |\n| figlet | high | CVE-2026-96780 | v3 | figlet is vulnerable to denial of service via unbounded loop when whitespaceBrea |\n| find-my-way | high | CVE-2026-47219 | v3 | find-my-way: DDoS with HTTP2 |\n| follow-redirects | high | CVE-2026-111756 | v5, v4, v3, v2, v1 | follow-redirects array-form headers bypass cross-origin credential stripping |\n| follow-redirects | high | CVE-2026-111755 | v5, v4, v3, v2, v1 | follow-redirects sensitiveHeaders regex escaping can expose credential headers |\n| follow-redirects | high | CVE-2026-116689 | v5, v4, v3, v2, v1 | follow-redirects: Cross-realm sensitiveHeaders arrays are discarded and custom c |\n| immutable | high | CVE-2026-59880 | v3, v1 | Immutable: Hash-collision algorithmic complexity denial of service in Immutable. |\n| immutable | high | CVE-2026-59879 | v3, v1 | Immutable.js `List` 32-bit trie overflow → unrecoverable DoS |\n| ip-address | high | CVE-2026-69192 | v3 | ip-address: Address4 decodes leading-zero octets as decimal while resolvers deco |\n| js-yaml | high | GHSA-5p4m-2wfm-xmqj | v1 | JS-YAML: Quadratic CPU consumption in !!omap resolution (3.x and 4.x) — CVE-2026 |\n| js-yaml | high | CVE-2026-84375 | v5, v4, v1 | js-yaml: maxTotalMergeKeys does not limit CPU use for empty merge sources |\n| launch-editor | high | CVE-2026-112942 | v1 | launch-editor: `fs.existsSync()` existence check can be bypassed on Windows |\n| linkify-it | high | CVE-2026-59887 | v3 | linkify-it: Quadratic-complexity DoS via the `mailto:` validator scan-loop on at |\n| lodash.pick | high | CVE-2020-8203 | v1 | Prototype Pollution in lodash |\n| markdown-it | high | CVE-2026-111759 | v3, v2, v1 | markdown-it: Quadratic complexity in smartquotes with unmatched closing quotes |\n| markdown-it | high | CVE-2026-111758 | v3, v2, v1 | markdown-it: Quadratic-time rendering of a single multi-line link reference defi |\n| minimatch | high | CVE-2026-27903 | v1 | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja |\n| minimatch | high | CVE-2026-27904 | v1 | minimatch ReDoS: nested *() extglobs generate catastrophically backtracking regu |\n| nanoid | high | CVE-2026-67213 | v3, v1 | nanoid: custom generators can loop indefinitely when size is zero |\n| nanoid | high | CVE-2026-67214 | v3 | nanoid: non-secure generators can loop indefinitely with negative size |\n| postcss | high | CVE-2026-73646 | v3 | PostCSS: Path Traversal in Previous Source Map Auto-Loading (sourceMappingURL) l |\n| react-router | high | GHSA-qwww-vcr4-c8h2 | v3 | React Router: RSC Mode CSRF Bypass Allows Action Execution Before 400 Response |\n| serialize-javascript | high | GHSA-5c6j-r48x-rmvq | v1 | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to |\n| seroval | high | CVE-2026-104845 | v2, v1 | Seroval: Memory exhaustion via unchecked TypedArray length in JSON deserializati |\n| seroval | high | CVE-2026-116581 | v2, v1 | Seroval: fromJSON deserializer trusts node-supplied array length and sequence do |\n| seroval | high | CVE-2026-116584 | v2, v1 | Seroval `fromJSON`/`fromCrossJSON` denial of service via unvalidated array node |\n| seroval | high | CVE-2026-116580 | v2, v1 | Seroval: Deserialization invokes attacker-chosen callables: AsyncIteratorFactory |\n| simple-git | high | CVE-2026-102826 | v5, v4 | simple-git allows command execution through unblocked Git configuration includes |\n| simple-git | high | CVE-2026-102827 | v5, v4 | simple-git: unsafe-operations plugin bypass via git long-option abbreviation (-- |\n| source-map-js | high | CVE-2026-93749 | v3, v2, v1 | source-map-js allows event-loop denial of service through indexed source-map sec |\n| vite | high | CVE-2026-112942 | v3, v2 | launch-editor: `fs.existsSync()` existence check can be bypassed on Windows |\n| webpack-dev-middleware | high | CVE-2026-76844 | v1 | webpack-dev-middleware vulnerable to Path Traversal via non-slash-terminated pub |\n| zod | high | CVE-2023-54404 | v3 | Zod can exhaust memory while validating oversized constrained collections |\n| @angular/common | moderate | CVE-2026-88059 | v3 | Angular: Information Leak via `HttpTransferCache` Bypass When Using `withRequest |\n| @angular/compiler | moderate | CVE-2026-88057 | v3 | Angular: Sanitization bypass via directive host bindings on concrete host elemen |\n| @angular/core | moderate | CVE-2026-88057 | v3 | Angular: Sanitization bypass via directive host bindings on concrete host elemen |\n| @hono/node-server | moderate | GHSA-frvp-7c67-39w9 | v3 | Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encode |\n| @hono/node-server | moderate | CVE-2026-118663 | v5, v4, v3 | @hono/node-server: `serveStatic` decodes the request path a second time, leading |\n| @modelcontextprotocol/sdk | moderate | CVE-2026-111771 | v3 | MCP TypeScript SDK: Server bearer authentication accepted tokens issued for anot |\n| @modelcontextprotocol/sdk | moderate | CVE-2026-111769 | v3 | MCP TypeScript client SDK: HTTP client transports and OAuth requests followed cr |\n| axios | moderate | CVE-2026-101908 | v1 | Axios: Prototype pollution gadget in fetch adapter can alter outbound requests |\n| axios | moderate | CVE-2026-101902 | v1 | Axios: Prototype-Pollution Gadget in the Default Instance Allows Inherited Objec |\n| axios | moderate | CVE-2026-101904 | v1 | Axios: Header Injection via Inherited headers After Minimal Interceptor |\n| axios | moderate | CVE-2026-101900 | v1 | Axios: Fetch Adapter Header Injection via Inherited FormData getHeaders |\n| axios | moderate | CVE-2026-101899 | v1 | Axios: CIDR-form NO_PROXY entries are ignored, causing proxy exclusion bypass fo |\n| baseline-browser-mapping | moderate | CVE-2026-45819 | v1 | baseline-browser-mapping process termination on invalid input causes denial of s |\n| brace-expansion | moderate | CVE-2026-45149 | v1 | brace-expansion: Large numeric range defeats documented `max` DoS protection |\n| brace-expansion | moderate | CVE-2026-102277 | v5, v4, v1 | brace-expansion: Quadratic-time expansion of the `{a},b}` rewrite causes CPU den |\n| dompurify | moderate | GHSA-55q2-fjhq-7xh7 | v1 | DOMPurify: IN_PLACE hook removal leaves a detached subtree executable, causing X |\n| fast-uri | moderate | CVE-2026-86472 | v5, v4, v3, v1 | fast-uri vulnerable to inconsistent host case normalization via percent-encoded |\n| fast-uri | moderate | CVE-2026-110306 | v5, v4, v3, v1 | fast-uri vulnerable to URI scheme spoofing via percent-encoded scheme decoding |\n| fast-uri | moderate | CVE-2026-110180 | v5, v4, v1 | fast-uri vulnerable to host confusion via unchecked WHATWG host canonicalization |\n| fastify | moderate | CVE-2026-18504 | v3 | fastify vulnerable to schema validation bypass via root primitive coercion misma |\n| fastify | moderate | CVE-2026-16732 | v3 | fastify vulnerable to X-Forwarded-* spoofing under trustProxy hop-count |\n| fastify | moderate | CVE-2026-92081 | v3 | fastify vulnerable to Denial of Service via unhandled exception on HTTP/2 traile |\n| glob | moderate | CVE-2026-118773 | v5, v4, v1 | Glob: AbortSignal cancellation bypass allows post-timeout filesystem traversal |\n| handlebars | moderate | CVE-2026-106444 | v5, v4 | Handlebars: JavaScript Injection via Unsafe Inline Embedding of Precompiled Temp |\n| hono | moderate | CVE-2026-59897 | v3 | Hono: API Gateway v1 adapter can drop a distinct repeated request header value d |\n| hono | moderate | CVE-2026-59896 | v3 | hono/jsx does not isolate context per request, leading to cross-request data dis |\n| hono | moderate | CVE-2026-59895 | v3 | Hono: Server-Side XSS via JSX Escaping Bypass in cx() Utility |\n| hono | moderate | CVE-2026-69207 | v3 | Hono: ReDoS in CORS middleware via Access-Control-Request-Headers |\n| hono | moderate | CVE-2026-71850 | v3 | Hono: `memo()` retains SSR output across requests, leading to cross-user data di |\n| hono | moderate | CVE-2026-71848 | v3 | Hono: Algorithmic Complexity DoS in Language Middleware |\n| hono | moderate | CVE-2026-84365 | v3 | Hono: Incomplete fix for CVE-2026-39408: `toSSG()` still writes files outside th |\n| hono | moderate | CVE-2026-84364 | v3 | Hono: Unbounded dot-notation nesting in `parseBody()` can cause memory exhaustio |\n| hono | moderate | CVE-2026-84363 | v3 | Hono: Query parser reads parameters after the URL fragment, causing cache-key an |\n| hono | moderate | CVE-2026-93981 | v3 | hono/jsx renders plain strings unescaped in boundary components, leading to XSS |\n| hono | moderate | CVE-2026-111757 | v3 | Hono: `serveStatic` decodes the request path a second time, leading to bypass of |\n| ip-address | moderate | CVE-2026-101913 | v5, v4, v3, v1 | ip-address: Address6.isLinkLocal() recognizes fe80::/64 rather than fe80::/10, a |\n| ip-address | moderate | CVE-2026-101910 | v5, v4, v3, v1 | ip-address: no classifier recognizes the NAT64 local-use range 64:ff9b:1::/48, a |\n| ip-address | moderate | CVE-2026-101912 | v5, v4, v3, v1 | ip-address: isInSubnet() and isHostInSubnet() compare addresses of different fam |\n| ip-address | moderate | CVE-2026-101911 | v5, v4, v3, v1 | ip-address: Address6 builds a parse diagnostic proportional to the input with no |\n| ip-address | moderate | CVE-2026-111997 | v5, v4, v3, v1 | ip-address: Address6 matches a zone identifier in quadratic time ahead of its le |\n| ip-address | moderate | CVE-2026-69198 | v3 | ip-address: a CIDR suffix on the parsed address suppresses special-use classific |\n| ip-address | moderate | CVE-2026-54272 | v3 | ip-address: misclassification of IPv4-mapped/NAT64 IPv6 addresses can bypass SSR |\n| launch-editor | moderate | CVE-2026-112943 | v1 | launch-editor: escapeCmdArgs() omits % escaping on Windows |\n| launch-editor | moderate | CVE-2026-112944 | v1 | launch-editor: Editor CLI flag misinterpretation causing arbitrary command execu |\n| markdown-it | moderate | GHSA-253c-mchw-3w2r | v3, v2, v1 | markdown-it linkify: true has two quadratic paths, so a few hundred KB of markdo |\n| minimatch | moderate | CVE-2026-118764 | v5, v4, v1 | minimatch has potential denial of service via globparts amplification |\n| postcss | moderate | CVE-2026-69153 | v3 | PostCSS: incomplete fix of GHSA-6g55-p6wh-862q — attacker-controlled sourceMappi |\n| postcss-selector-parser | moderate | CVE-2026-104844 | v1 | PostCSS: Quadratic complexity in flat selector parsing allows CPU exhaustion |\n| protobufjs | moderate | CVE-2026-59876 | v3 | protobufjs: Text Format string map parsing can mutate returned map object protot |\n| protobufjs | moderate | CVE-2026-59877 | v3 | protobufjs: Denial of Service via infinite loop in .proto option parsing |\n| qs | moderate | CVE-2026-8723 | v1 | qs has a remotely triggerable DoS: qs.stringify crashes with TypeError on null/u |\n| qs | moderate | CVE-2026-82562 | v4, v3, v2, v1 | qs array-limit bypass via bracket-key comma parsing |\n| qs | moderate | CVE-2026-82417 | v4, v3, v2, v1 | qs: Denial of Service via Attacker Controlled isBuffer |\n| qs | moderate | CVE-2026-110816 | v4, v3, v2, v1 | qs : qs.stringify with arrayFormat 'comma' throws an uncaught TypeError on array |\n| react-router-dom | moderate | CVE-2026-53668 | v1 | React Router: Open redirect leading to XSS |\n| serialize-javascript | moderate | CVE-2026-34043 | v1 | Serialize JavaScript has CPU Exhaustion Denial of Service via crafted array-like |\n| seroval | moderate | CVE-2026-116582 | v2, v1 | Seroval: Script injection through RegExp sources in serialized output |\n| vite | moderate | CVE-2026-112943 | v3, v2 | launch-editor: escapeCmdArgs() omits % escaping on Windows |\n| vite | moderate | CVE-2026-112944 | v3, v2 | launch-editor: Editor CLI flag misinterpretation causing arbitrary command execu |\n| vite | moderate | CVE-2026-112946 | v3, v2 | Vite: Files outside `server.fs.allow` could be served when project paths match s |\n| @grpc/grpc-js | low | CVE-2026-101915 | v3 | @grpc/grpc-js: The server transmits some error messages thrown by method handler |\n| body-parser | low | CVE-2026-12590 | v3 | body-parser vulnerable to denial of service when invalid limit value silently di |\n| deepmerge | low | CVE-2026-93753 | v5, v4, v3, v2, v1 | deepmerge mergeObject() allows prototype poisoning of returned objects |\n| dompurify | low | GHSA-6688-9rhm-gjv2 | v1 | DOMPurify: IN_PLACE returns a force-removed rawtext root whose text carries atta |\n| dompurify | low | GHSA-c6gr-qvv4-5v3f | v1 | DOMPurify: SMIL attributeName=href guard is skipped when PARSER_MEDIA_TYPE is ap |\n| fast-uri | low | CVE-2026-110095 | v5, v4, v3, v1 | fast-uri vulnerable to improper path equivalence in relative reference normaliza |\n| fast-uri | low | CVE-2026-110725 | v5, v4, v3, v1 | fast-uri vulnerable to scheme injection via an unescaped first-segment colon in |\n| hono | low | CVE-2026-71849 | v3 | Hono: Proxy Helper does not remove response headers listed in the `Connection` h |\n| markdown-it | low | CVE-2026-111766 | v3, v2, v1 | markdown-it: Quadratic-time denial of service in inline HTML parsing with html e |\n| postcss-selector-parser | low | CVE-2026-9358 | v1 | postcss-selector-parser allows denial of service through uncontrolled AST recurs |\n| serialize-javascript | low | CVE-2026-115897 | v1 | Serialize JavaScript: Cross-site scripting (XSS) via unescaped </script at the e |\n| vite | low | CVE-2026-112945 | v3, v2 | Vite: Cross origin script execution through Vite custom middleware |\n\n## 2. All Dependencies\n\n### Summary\n\n| Severity | v5 | v4 | v3 | v2 | v1 |\n| -------- | --: | --: | --: | --: | --: |\n| critical | 6 | 7 | 14 | 10 | 11 |\n| high | 81 | 81 | 168 | 149 | 100 |\n| moderate | 71 | 71 | 143 | 131 | 70 |\n| low | 9 | 9 | 26 | 29 | 13 |\n| info | 0 | 0 | 0 | 0 | 0 |\n| unknown | 0 | 0 | 0 | 0 | 0 |\n\n### Vulnerabilities\n\n| Package | Severity | CVE | Affected Versions | Description |\n| --------------------------------------- | -------- | ------------------- | ------------------ | -------------------------------------------------------------------------------- |\n| @simple-git/argv-parser | critical | CVE-2026-102829 | v5, v4 | simple-git: `VISUAL` editor environment variable is omitted from unsafe editor d |\n| basic-ftp | critical | CVE-2026-27699 | v3 | Basic FTP has Path Traversal Vulnerability in its downloadToDir() method |\n| dompurify | critical | GHSA-cg2g-xh64-v4q7 | v1 | DOMPurify SAFE_FOR_TEMPLATES bypass: split template expressions survive in attac |\n| fast-xml-parser | critical | CVE-2026-25896 | v3, v2 | fast-xml-parser has an entity encoding bypass via regex injection in DOCTYPE ent |\n| handlebars | critical | CVE-2026-33937 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion |\n| handlebars | critical | CVE-2026-106446 | v5, v4, v3, v2, v1 | Handlebars: JavaScript Injection via AST Type Confusion in compile (bypass of CV |\n| handlebars | critical | CVE-2026-106445 | v5, v4, v3, v2, v1 | Handlebars: JavaScript Injection via Own Property Check Bypass |\n| locutus | critical | CVE-2026-32304 | v3, v2, v1 | Locutus vulnerable to RCE via unsanitized input in create_function() |\n| locutus | critical | CVE-2026-25521 | v3, v1 | locutus is vulnerable to Prototype Pollution |\n| piscina | critical | CVE-2026-102992 | v5, v4, v3, v2 | piscina: Prototype-pollution gadget in ThreadPool.options allows RCE via execArg |\n| proxy-addr | critical | CVE-2026-90711 | v4, v3, v2, v1 | proxy-addr vulnerable to IP spoofing via IPv4-mapped IPv6 trust subnet |\n| seroval | critical | CVE-2026-59940 | v3, v2, v1 | seroval: `seroval.fromJSON()` Promise resolver type confusion invokes attacker-c |\n| seroval | critical | CVE-2026-104846 | v3, v2, v1 | Seroval: `fromJSON()` Promise thenable assimilation invokes plugin-produced call |\n| shell-quote | critical | CVE-2026-102422 | v5, v4, v2, v1 | shell-quote: `quote()` command injection via a line terminator in a token after |\n| shell-quote | critical | CVE-2026-9277 | v3 | shell-quote quote() does not escape newlines in object .op values |\n| simple-git | critical | CVE-2026-102828 | v5, v4 | simple-git unsafe-operation guard does not block trailer command configuration |\n| tar | critical | CVE-2026-59873 | v3, v1 | node-tar: Decompression/parse DoS via unlimited input |\n| websocket-driver | critical | CVE-2026-54466 | v3, v2 | websocket-driver: Message corruption via abuse of protocol length headers |\n| @angular/common | high | CVE-2025-66035 | v1 | Angular is Vulnerable to XSRF Token Leakage via Protocol-Relative URLs in Angula |\n| @angular/common | high | CVE-2026-54268 | v3, v1 | @angular/common: Denial of Service (DoS) via OOM in Date Formatting (formatDate) |\n| @angular/common | high | CVE-2026-54266 | v3, v1 | @angular/common: Weak 32-Bit Cache Key Hashing in `HttpTransferCache` Leading to |\n| @angular/common | high | CVE-2026-50171 | v1 | @angular/common: Denial of Service (DoS) via OOM in Number Formatting (digitsInf |\n| @angular/common | high | CVE-2026-50170 | v1 | @angular/common: Information Leak via Default Caching of Credentialed Requests i |\n| @angular/common | high | CVE-2026-68945 | v3, v1 | Angular: Cache-Key Ambiguity in HttpTransferCache Leading to Cross-Request Respo |\n| @angular/compiler | high | CVE-2026-32635 | v1 | Angular vulnerable to XSS in i18n attribute bindings |\n| @angular/compiler | high | CVE-2026-22610 | v1 | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes |\n| @angular/compiler | high | CVE-2025-66412 | v1 | Angular Stored XSS Vulnerability via SVG Animation, SVG URL and MathML Attribute |\n| @angular/compiler | high | CVE-2026-69151 | v5, v4, v3, v1 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/core | high | CVE-2026-27970 | v1 | Angular i18n vulnerable to Cross-Site Scripting |\n| @angular/core | high | CVE-2026-32635 | v1 | Angular vulnerable to XSS in i18n attribute bindings |\n| @angular/core | high | CVE-2026-22610 | v1 | Angular has XSS Vulnerability via Unsanitized SVG Script Attributes |\n| @angular/core | high | CVE-2026-54267 | v5, v4, v3, v1 | Angular Client Hydration DOM Clobbering & Response-Cache Poisoning |\n| @angular/core | high | CVE-2026-69151 | v5, v4, v3, v2, v1 | Angular i18n: Cross-Site Scripting (XSS) via event-handler attributes |\n| @angular/router | high | CVE-2026-101896 | v3, v2 | Angular Server-Side Rendering (SSR): Denial of Service via Numeric URL Matrix Pa |\n| @angular/router | high | CVE-2026-111752 | v3, v2 | @angular/router: Denial of Service via Unmatched Empty-Path Outlet Route Matchin |\n| @angular/router | high | CVE-2026-111751 | v3, v2 | @angular/router: Denial of Service via RouterLink Query Parameter Retention in S |\n| @grpc/grpc-js | high | CVE-2026-101916 | v3 | @grpc/grpc-js: In certain configurations, getAuthContext can return unauthorized |\n| @hono/node-server | high | CVE-2026-29087 | v2 | @hono/node-server has authorization bypass for protected static paths via encode |\n| @modelcontextprotocol/sdk | high | CVE-2026-104850 | v3, v2 | MCP TypeScript SDK: OAuth client could send credentials to an authorization serv |\n| @modelcontextprotocol/sdk | high | CVE-2026-111767 | v5, v4, v3, v2 | MCP TypeScript SDK: Experimental tasks were not tied to the session that created |\n| @modelcontextprotocol/sdk | high | CVE-2026-111768 | v5, v4, v3, v2 | MCP TypeScript SDK: One HTTP request within the default size limit could exhaust |\n| @modelcontextprotocol/sdk | high | GHSA-f897-62hf-6gxq | v3, v2 | MCP TypeScript SDK: HTTP server transports and handlers did not limit request bo |\n| @vue/server-renderer | high | GHSA-g2v6-rqmx-r4w6 | v3, v2, v1 | @vue/server-renderer: XSS via missing CR in attribute-name blacklist |\n| @xmldom/xmldom | high | CVE-2026-83612 | v5, v4 | xmldom: HTML raw-text closing-tag case mismatch causes output amplification |\n| @xmldom/xmldom | high | CVE-2026-83606 | v5, v4 | xmldom PI grammar regex ReDoS: quadratic backtracking on unterminated processing |\n| @xmldom/xmldom | high | CVE-2026-83607 | v5, v4 | xmldom: Element name injection via createElement() bypasses requireWellFormed |\n| @xmldom/xmldom | high | CVE-2026-83605 | v5, v4 | xmldom: Attribute name injection via setAttribute() bypasses requireWellFormed |\n| @xmldom/xmldom | high | CVE-2026-83616 | v5, v4 | xmldom: Processing Instruction Target Injection Bypasses requireWellFormed |\n| @xmldom/xmldom | high | CVE-2026-83608 | v5, v4 | xmldom: DocType `name` Injection Bypasses requireWellFormed |\n| @xmldom/xmldom | high | CVE-2026-83609 | v5, v4 | xmldom: Creation-time XML Name/QName validation is bypassable via an embedded li |\n| @xmldom/xmldom | high | CVE-2026-83618 | v5, v4 | xmldom: requireWellFormed DocType publicId/systemId validation is bypassable via |\n| @xmldom/xmldom | high | CVE-2026-83613 | v5, v4 | xmldom: Quadratic-time attribute deduplication |\n| @xmldom/xmldom | high | CVE-2026-83615 | v5, v4 | xmldom: Quadratic-memory consumption |\n| @xmldom/xmldom | high | CVE-2026-83614 | v5, v4 | xmldom: Quadratic-time parsing via the malformed-input recovery path — `parseEle |\n| adm-zip | high | CVE-2026-77301 | v5, v4, v2 | adm-zip: Uncontrolled memory allocation via the declared uncompressed size (DoS) |\n| adm-zip | high | GHSA-rcw4-f5rp-g42v | v5, v4, v2 | adm-zip: Decompression-bomb protection (fix for CVE-2026-39244) can be bypassed |\n| adm-zip | high | CVE-2026-102282 | v5, v4, v2 | adm-zip extraction preserves SUID/SGID bits from untrusted ZIPs -> local privile |\n| adm-zip | high | GHSA-8238-w5pm-2374 | v5, v4, v2 | adm-zip: Unhandled error event in async DEFLATE decompression crashes Node.js pr |\n| axios | high | CVE-2026-101903 | v5, v4, v2, v1 | Axios: ReDoS in fromDataURI data: URL parser freezes the Node event loop (DoS) |\n| axios | high | CVE-2026-101906 | v5, v4, v2, v1 | Axios: ReDoS (O(N²)) in shouldBypassProxy host normalization, reachable via untr |\n| axios | high | CVE-2026-101909 | v5, v4, v2, v1 | Axios: Prototype Pollution Gadget in axios toFormData Options |\n| axios | high | CVE-2026-101898 | v5, v4, v2, v1 | Axios: HTTP/2 adapter bypasses configured DNS lookup and proxy controls |\n| axios | high | CVE-2026-101901 | v5, v4, v2, v1 | Axios: Denial of Service via Unhandled 'error' Event in HTTP/2 ClientHttp2Sessio |\n| axios | high | CVE-2026-101905 | v5, v4, v2, v1 | Axios: Node HTTP adapter prototype-pollution gadget allows request socket hijack |\n| axios | high | CVE-2026-101907 | v5, v4, v2, v1 | Axios: maxRedirects: 0 is not enforced by the fetch adapter, allowing redirect-b |\n| axios | high | CVE-2026-42043 | v3 | Axios: Incomplete Fix for CVE-2025-62718 — NO_PROXY Protection Bypassed via RFC |\n| axios | high | CVE-2026-42033 | v3 | Axios: Prototype Pollution Gadgets - Response Tampering, Data Exfiltration, and |\n| axios | high | CVE-2026-42035 | v3 | Axios: Header Injection via Prototype Pollution |\n| axios | high | CVE-2026-25639 | v3 | Axios is Vulnerable to Denial of Service via **proto** Key in mergeConfig |\n| axios | high | CVE-2026-42264 | v3 | Axios has prototype pollution read-side gadgets in HTTP adapter that allow crede |\n| axios | high | CVE-2026-44496 | v3 | Axios: Regular Expression Denial of Service (ReDoS) via Cookie Name Injection |\n| axios | high | CVE-2026-44488 | v3 | Allocation of Resources Without Limits or Throttling in Axios |\n| axios | high | CVE-2026-44487 | v3 | Axios: Proxy-Authorization Credential Leak to Origin Server Across HTTP-to-HTTPS |\n| axios | high | CVE-2026-44486 | v3 | Axios: Proxy-Authorization header leaks to redirect target when proxy is re-eval |\n| axios | high | CVE-2026-44495 | v3 | axios Vulnerable to Credential Theft and Response Hijacking via Prototype Pollut |\n| axios | high | CVE-2026-44494 | v3 | axios Vulnerable to Full Man-in-the-Middle via Prototype Pollution Gadget in `co |\n| basic-ftp | high | CVE-2026-102990 | v5, v4, v3, v2, v1 | basic-ftp: Quadratic-time CPU denial of service in Client.list() Unix directory- |\n| basic-ftp | high | GHSA-6v7q-wjvx-w8wg | v3 | basic-ftp: Incomplete CRLF Injection Protection Allows Arbitrary FTP Command Exe |\n| basic-ftp | high | CVE-2026-41324 | v3 | basic-ftp vulnerable to denial of service via unbounded memory consumption in Cl |\n| basic-ftp | high | CVE-2026-44240 | v3 | basic-ftp allows a malicious FTP server to cause client-side denial of service v |\n| body-parser | high | CVE-2026-111181 | v5, v4, v3, v2, v1 | body-parser vulnerable to Denial of Service via trailing bytes after a compresse |\n| brace-expansion | high | CVE-2026-13149 | v3, v2, v1 | brace-expansion: DoS via exponential-time expansion of consecutive non-expanding |\n| brace-expansion | high | CVE-2026-14257 | v3, v2, v1 | brace-expansion: DoS via unbounded expansion length causing an out-of-memory pro |\n| brace-expansion | high | CVE-2026-69152 | v3, v2, v1 | brace-expansion: DoS via unbounded intermediate arrays, bypassing the CVE-2026-1 |\n| brace-expansion | high | CVE-2026-102278 | v5, v4, v3, v2, v1 | brace-expansion: DoS via uncontrolled recursion on nested brace groups causing s |\n| brace-expansion | high | CVE-2026-102276 | v5, v4, v3, v2, v1 | brace-expansion: DoS via uncontrolled recursion in parseCommaParts causing stack |\n| braces | high | CVE-2024-4068 | v3, v2, v1 | Uncontrolled resource consumption in braces |\n| browserslist | high | CVE-2026-73089 | v3, v2, v1 | Browserslist: Unbounded memory growth (no cache eviction) via distinct query res |\n| browserslist | high | CVE-2026-73088 | v3, v2, v1 | Browserslist: Uncaught crash / prototype write via untrusted browserslist-stats. |\n| compression | high | CVE-2026-87776 | v5, v4, v3, v2, v1 | compression vulnerable to Denial of Service via memory leak on premature respons |\n| decode-uri-component | high | CVE-2026-118664 | v3, v2, v1 | decode-uri-component vulnerable to denial of service via quadratic replacement o |\n| deepmerge-ts | high | CVE-2026-40345 | v3, v2 | DeepmergeTS has stack exhaustion when merging recursive object graphs |\n| dompurify | high | GHSA-mrv2-3pqr-j5jr | v1 | DOMPurify IN_PLACE: hook that removes a parent or sibling leaves the detached su |\n| engine.io | high | CVE-2026-59725 | v3, v2 | Socket.IO: Engine.IO Polling Transport Connection Exhaustion |\n| engine.io | high | CVE-2026-59724 | v3, v2 | Socket.IO: Engine.IO WebTransport SID DoS |\n| engine.io | high | CVE-2026-102599 | v5, v4, v3, v2 | Socket.IO: Engine.IO Protocol Revision Mismatch DoS |\n| express-rate-limit | high | CVE-2026-30827 | v2 | express-rate-limit: IPv4-mapped IPv6 addresses bypass per-client rate limiting o |\n| extract-zip | high | CVE-2026-56876 | v5, v4, v3, v2, v1 | extract-zip unvalidated symlink path traversal |\n| extract-zip | high | CVE-2026-19693 | v5, v4, v3, v2, v1 | extract-zip allows arbitrary file writes through symlink archive entries |\n| fast-uri | high | CVE-2026-18446 | v3, v2, v1 | fast-uri vulnerable to host confusion via backslash authority introducer |\n| fast-uri | high | CVE-2026-75931 | v5, v4, v1 | fast-uri vulnerable to host confusion via skipped IDN canonicalization on scheme |\n| fast-uri | high | CVE-2026-75975 | v5, v4, v3, v2, v1 | fast-uri vulnerable to server-side request forgery via malformed IPv6 normalizat |\n| fast-uri | high | CVE-2026-75899 | v5, v4, v3, v1 | fast-uri vulnerable to server-side request forgery via repeated hostname percent |\n| fast-uri | high | CVE-2026-76172 | v5, v4, v3, v2, v1 | fast-uri vulnerable to host confusion via percent-encoded scheme normalization |\n| fast-uri | high | CVE-2026-84292 | v5, v4, v3, v2, v1 | fast-uri vulnerable to authority injection via an unvalidated port in serialize |\n| fast-uri | high | CVE-2026-16221 | v3, v2 | fast-uri vulnerable to host confusion via literal backslash authority delimiter |\n| fast-uri | high | CVE-2026-6321 | v2 | fast-uri vulnerable to path traversal via percent-encoded dot segments |\n| fast-uri | high | CVE-2026-6322 | v2 | fast-uri vulnerable to host confusion via percent-encoded authority delimiters |\n| fast-uri | high | CVE-2026-13676 | v3, v2 | fast-uri vulnerable to host confusion via failed IDN canonicalization |\n| fast-xml-parser | high | CVE-2026-25128 | v3, v2 | fast-xml-parser has RangeError DoS Numeric Entities Bug |\n| fast-xml-parser | high | CVE-2026-26278 | v3, v2 | fast-xml-parser affected by DoS through entity expansion in DOCTYPE (no expansio |\n| fast-xml-parser | high | CVE-2026-33036 | v3, v2 | fast-xml-parser affected by numeric entity expansion bypassing all entity expans |\n| fastify | high | CVE-2026-84504 | v3 | fastify vulnerable to request body replacement via an async validation result co |\n| fastify | high | CVE-2026-76169 | v3 | fastify vulnerable to authentication bypass via malformed URLs reaching encapsul |\n| fastify | high | CVE-2026-84469 | v3 | fastify vulnerable to request validation bypass via skipped boolean false schema |\n| fastify | high | CVE-2026-84428 | v3 | fastify vulnerable to header validation bypass via incomplete schema case normal |\n| figlet | high | CVE-2026-96780 | v3 | figlet is vulnerable to denial of service via unbounded loop when whitespaceBrea |\n| find-my-way | high | CVE-2026-47219 | v3 | find-my-way: DDoS with HTTP2 |\n| flatted | high | CVE-2026-32141 | v3, v2 | flatted vulnerable to unbounded recursion DoS in parse() revive phase |\n| flatted | high | CVE-2026-33228 | v3, v2 | Prototype Pollution via parse() in NodeJS flatted |\n| follow-redirects | high | CVE-2026-111756 | v5, v4, v3, v2, v1 | follow-redirects array-form headers bypass cross-origin credential stripping |\n| follow-redirects | high | CVE-2026-111755 | v5, v4, v3, v2, v1 | follow-redirects sensitiveHeaders regex escaping can expose credential headers |\n| follow-redirects | high | CVE-2026-116689 | v5, v4, v3, v2, v1 | follow-redirects: Cross-realm sensitiveHeaders arrays are discarded and custom c |\n| form-data | high | CVE-2026-12143 | v3, v2, v1 | form-data: CRLF injection in form-data via unescaped multipart field names and f |\n| handlebars | high | CVE-2026-33938 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion by tampering @part |\n| handlebars | high | CVE-2026-33940 | v3, v1 | Handlebars.js has JavaScript Injection via AST Type Confusion when passing an ob |\n| handlebars | high | CVE-2026-33939 | v3, v1 | Handlebars.js has Denial of Service via Malformed Decorator Syntax in Template C |\n| handlebars | high | CVE-2026-33941 | v3, v1 | Handlebars.js has JavaScript Injection in CLI Precompiler via Unescaped Names an |\n| happy-dom | high | CVE-2026-115895 | v5, v4 | Happy DOM: Incomplete fix for CVE-2026-33943: unsanitized import alias leads to |\n| happy-dom | high | CVE-2026-118660 | v5, v4 | Happy DOM: SSRF via iframe and link stylesheet when parsing untrusted HTML |\n| hono | high | CVE-2026-29045 | v2 | Hono vulnerable to arbitrary file access via serveStatic vulnerability |\n| hono | high | CVE-2026-54290 | v2 | hono: CORS Middleware reflects any Origin with credentials when `origin` default |\n| http-proxy-middleware | high | CVE-2026-55603 | v3 | http-proxy-middleware: multipart/form-data field injection via unescaped CRLF in |\n| immutable | high | CVE-2026-59880 | v3, v2, v1 | Immutable: Hash-collision algorithmic complexity denial of service in Immutable. |\n| immutable | high | CVE-2026-59879 | v3, v2, v1 | Immutable.js `List` 32-bit trie overflow → unrecoverable DoS |\n| immutable | high | CVE-2026-29063 | v2 | Immutable is vulnerable to Prototype Pollution |\n| ip-address | high | CVE-2026-69192 | v3, v2 | ip-address: Address4 decodes leading-zero octets as decimal while resolvers deco |\n| js-yaml | high | GHSA-5p4m-2wfm-xmqj | v3, v2, v1 | JS-YAML: Quadratic CPU consumption in !!omap resolution (3.x and 4.x) — CVE-2026 |\n| js-yaml | high | CVE-2026-84375 | v5, v4, v3, v2, v1 | js-yaml: maxTotalMergeKeys does not limit CPU use for empty merge sources |\n| js-yaml | high | CVE-2026-59869 | v3, v2 | js-yaml: YAML merge-key chains can force quadratic CPU consumption |\n| launch-editor | high | CVE-2026-112942 | v5, v4, v3, v2, v1 | launch-editor: `fs.existsSync()` existence check can be bypassed on Windows |\n| linkify-it | high | CVE-2026-59887 | v3 | linkify-it: Quadratic-complexity DoS via the `mailto:` validator scan-loop on at |\n| locutus | high | CVE-2026-29091 | v3, v2, v1 | locutus call_user_func_array vulnerable to Remote Code Execution (RCE) due to Co |\n| lodash | high | CVE-2026-4800 | v3 | lodash vulnerable to Code Injection via `_.template` imports key names |\n| lodash.pick | high | CVE-2020-8203 | v2, v1 | Prototype Pollution in lodash |\n| markdown-it | high | CVE-2026-111759 | v3, v2, v1 | markdown-it: Quadratic complexity in smartquotes with unmatched closing quotes |\n| markdown-it | high | CVE-2026-111758 | v3, v2, v1 | markdown-it: Quadratic-time rendering of a single multi-line link reference defi |\n| minimatch | high | CVE-2026-27903 | v3, v2, v1 | minimatch has ReDoS: matchOne() combinatorial backtracking via multiple non-adja |\n| minimatch | high | CVE-2026-27904 | v3, v2, v1 | minimatch ReDoS: nested *() extglobs generate catastrophically backtracking regu |\n| minimatch | high | CVE-2026-26996 | v3, v2 | minimatch has a ReDoS via repeated wildcards with non-matching literal in patter |\n| nanoid | high | CVE-2026-67213 | v3, v1 | nanoid: custom generators can loop indefinitely when size is zero |\n| nanoid | high | CVE-2026-67214 | v3 | nanoid: non-secure generators can loop indefinitely with negative size |\n| nanoid | high | CVE-2026-73086 | v3 | nanoid: Integer Overflow or Wraparound |\n| node-forge | high | CVE-2026-33896 | v2 | Forge has a basicConstraints bypass in its certificate chain verification (RFC 5 |\n| node-forge | high | CVE-2026-33895 | v2 | Forge has signature forgery in Ed25519 due to missing S > L check |\n| node-forge | high | CVE-2026-33891 | v2 | Forge has Denial of Service via Infinite Loop in BigInteger.modInverse() with Ze |\n| node-forge | high | CVE-2026-33894 | v2 | Forge has signature forgery in RSA-PKCS due to ASN.1 extra field |\n| node-forge | high | CVE-2026-85393 | v2 | node-forge RSA PKCS#1 v1.5 signature verification accepts extra nested DigestAlg |\n| node-forge | high | CVE-2026-118779 | v2 | Forge: Regular expression denial of service in PEM decoding (pem.decode) |\n| node-forge | high | CVE-2026-118782 | v2 | Forge: PKCS#12 MAC forgery and constant-key PBE via zero iteration count |\n| node-forge | high | CVE-2026-119188 | v2 | Forge: Denial of service in TLS record processing via a record interleaved with |\n| node-forge | high | CVE-2026-119187 | v2 | Forge: Denial of service in TLS record processing via call stack exhaustion |\n| node-forge | high | CVE-2026-119190 | v2 | Forge: X.509 basicConstraints bypass in verifyCertificateChain() via deprecated |\n| nx | high | CVE-2026-71476 | v3, v1 | Nx: Zip-Slip in the self-hosted remote cache |\n| nx | high | GHSA-w2vw-w76x-qr89 | v3, v1 | Nx: OS command injection via git revisions and remote refs |\n| nx | high | CVE-2026-104854 | v3, v2, v1 | Nx daemon and plugin worker sockets are accessible to other local users |\n| pacote | high | CVE-2026-9496 | v3, v2, v1 | pacote is vulnerable to Denial of Service (DoS) via the addGitSha function |\n| path-to-regexp | high | CVE-2026-4867 | v3, v2 | path-to-regexp vulnerable to Regular Expression Denial of Service via multiple r |\n| path-to-regexp | high | CVE-2026-4926 | v2 | path-to-regexp vulnerable to Denial of Service via sequential optional groups |\n| piscina | high | CVE-2026-55388 | v3 | piscina: Prototype Pollution Gadget → RCE via inherited options.filename |\n| postcss | high | CVE-2026-45623 | v5, v4, v3, v2 | PostCSS: Arbitrary file read and information disclosure via attacker-controlled |\n| postcss | high | CVE-2026-73646 | v5, v4, v3, v2 | PostCSS: Path Traversal in Previous Source Map Auto-Loading (sourceMappingURL) l |\n| react-router | high | GHSA-qwww-vcr4-c8h2 | v3 | React Router: RSC Mode CSRF Bypass Allows Action Execution Before 400 Response |\n| rollup | high | CVE-2026-27606 | v1 | Rollup 4 has Arbitrary File Write via Path Traversal |\n| semver | high | CVE-2022-25883 | v2 | semver vulnerable to Regular Expression Denial of Service |\n| serialize-javascript | high | GHSA-5c6j-r48x-rmvq | v5, v4, v3, v2, v1 | Serialize JavaScript is Vulnerable to RCE via RegExp.flags and Date.prototype.to |\n| seroval | high | CVE-2026-104845 | v3, v2, v1 | Seroval: Memory exhaustion via unchecked TypedArray length in JSON deserializati |\n| seroval | high | CVE-2026-116581 | v3, v2, v1 | Seroval: fromJSON deserializer trusts node-supplied array length and sequence do |\n| seroval | high | CVE-2026-116584 | v3, v2, v1 | Seroval `fromJSON`/`fromCrossJSON` denial of service via unvalidated array node |\n| seroval | high | CVE-2026-116580 | v3, v2, v1 | Seroval: Deserialization invokes attacker-chosen callables: AsyncIteratorFactory |\n| shell-quote | high | CVE-2026-13311 | v3 | shell-quote: Quadratic-complexity Denial of Service in `parse()` (CWE-407) |\n| sigstore | high | CVE-2026-48815 | v3, v2, v1 | sigstore's `certificateOIDs` verification constraints are silently dropped and n |\n| simple-git | high | CVE-2026-102826 | v5, v4 | simple-git allows command execution through unblocked Git configuration includes |\n| simple-git | high | CVE-2026-102827 | v5, v4 | simple-git: unsafe-operations plugin bypass via git long-option abbreviation (-- |\n| smol-toml | high | CVE-2026-85730 | v3, v2, v1 | smol-toml: Denial of Service via malformed TOML documents |\n| socket.io-parser | high | CVE-2026-33151 | v3, v2 | socket.io allows an unbounded number of binary attachments |\n| socket.io-parser | high | CVE-2026-69185 | v3, v2 | Socket.IO: Zero-attachment Memory Exhaustion |\n| source-map-js | high | CVE-2026-93749 | v3, v2, v1 | source-map-js allows event-loop denial of service through indexed source-map sec |\n| svgo | high | CVE-2026-29074 | v3, v2, v1 | SVGO DoS through entity expansion in DOCTYPE (Billion Laughs) |\n| svgo | high | CVE-2026-73650 | v3, v2, v1 | SVGO removeScripts plugin leaves some executable scripts intact |\n| svgo | high | CVE-2026-84370 | v5, v4, v3, v2, v1 | SVGO: removeScripts allows executable links through namespace and control-charac |\n| tar | high | CVE-2026-24842 | v1 | node-tar Vulnerable to Arbitrary File Creation/Overwrite via Hardlink Path Trave |\n| tar | high | CVE-2026-23745 | v1 | node-tar is Vulnerable to Arbitrary File Overwrite and Symlink Poisoning via Ins |\n| tar | high | CVE-2026-26960 | v1 | Arbitrary File Read/Write via Hardlink Target Escape Through Symlink Chain in no |\n| tar | high | CVE-2026-29786 | v1 | tar has Hardlink Path Traversal via Drive-Relative Linkpath |\n| tar | high | CVE-2026-31802 | v1 | node-tar Symlink Path Traversal via Drive-Relative Linkpath |\n| tar | high | CVE-2026-23950 | v1 | Race Condition in node-tar Path Reservations via Unicode Ligature Collisions on |\n| tar | high | CVE-2026-59874 | v3, v1 | node-tar: Negative tar entry size causes infinite loop in archive replace |\n| tar | high | CVE-2026-73566 | v3, v2, v1 | node-tar: Uncontrolled recursion in mapHas/filesFilter allows uncatchable stack- |\n| tmp | high | CVE-2026-44705 | v3, v2 | tmp has Path Traversal via unsanitized prefix/postfix that enables directory esc |\n| undici | high | CVE-2026-19534 | v5, v4, v3, v2 | undici vulnerable to Denial of Service via unrequested WebSocket subprotocol |\n| undici | high | CVE-2026-84961 | v3, v2 | undici vulnerable to TLS certificate validation bypass via dropped connect optio |\n| undici | high | CVE-2026-109869 | v5, v4, v3, v2 | undici vulnerable to Denial of Service via unhandled error on excessive content- |\n| undici | high | CVE-2026-109829 | v5, v4, v3, v2 | undici vulnerable to cache poisoning and cross-user disclosure via cross-origin |\n| undici | high | CVE-2026-109383 | v5, v4, v3, v2 | undici vulnerable to TLS certificate validation bypass via dropped tls options i |\n| undici | high | CVE-2026-87018 | v5, v4, v3, v2 | undici vulnerable to Denial of Service via TLS 1.2 certificate-changing renegoti |\n| undici | high | CVE-2026-1528 | v3 | Undici: Malicious WebSocket 64-bit length overflows parser and crashes the clien |\n| undici | high | CVE-2026-1526 | v3 | Undici has Unbounded Memory Consumption in WebSocket permessage-deflate Decompre |\n| undici | high | CVE-2026-2229 | v3 | Undici has Unhandled Exception in WebSocket Client Due to Invalid server_max_win |\n| undici | high | CVE-2026-9697 | v3 | undici vulnerable to TLS certificate validation bypass via dropped requestTls in |\n| undici | high | CVE-2026-6734 | v3 | undici vulnerable to cross-origin request routing via SOCKS5 proxy pool reuse |\n| undici | high | CVE-2026-13697 | v3 | undici vulnerable to cross-user information disclosure and parse-time crash via |\n| undici | high | CVE-2026-12151 | v3 | undici WebSocket client vulnerable to denial of service via fragment count bypas |\n| vite | high | CVE-2026-39364 | v1 | Vite: `server.fs.deny` bypassed with queries |\n| vite | high | CVE-2026-39363 | v1 | Vite Vulnerable to Arbitrary File Read via Vite Dev Server WebSocket |\n| vite | high | CVE-2026-112942 | v5, v4, v3, v2, v1 | launch-editor: `fs.existsSync()` existence check can be bypassed on Windows |\n| webpack-dev-middleware | high | CVE-2026-76844 | v2, v1 | webpack-dev-middleware vulnerable to Path Traversal via non-slash-terminated pub |\n| ws | high | CVE-2026-48779 | v3, v2, v1 | ws: Memory exhaustion DoS from tiny fragments and data chunks |\n| zod | high | CVE-2023-54404 | v3, v2, v1 | Zod can exhaust memory while validating oversized constrained collections |\n| @angular/common | moderate | CVE-2026-88059 | v3, v2, v1 | Angular: Information Leak via `HttpTransferCache` Bypass When Using `withRequest |\n| @angular/common | moderate | CVE-2026-111753 | v3, v2, v1 | @angular/common: XSRF Token Leakage via URL Parsing Discrepancy in Angular HTTP |\n| @angular/compiler | moderate | CVE-2026-54265 | v5, v4, v3, v1 | @angular/compiler: Two-Way Property Binding Sanitization Bypass (XSS) |\n| @angular/compiler | moderate | CVE-2026-50557 | v5, v4, v1 | Angular: Template and Attribute Namespace Sanitization Bypass (XSS) |\n| @angular/compiler | moderate | CVE-2026-88057 | v5, v4, v3, v2, v1 | Angular: Sanitization bypass via directive host bindings on concrete host elemen |\n| @angular/core | moderate | CVE-2026-50557 | v5, v4, v1 | Angular: Template and Attribute Namespace Sanitization Bypass (XSS) |\n| @angular/core | moderate | CVE-2026-52725 | v5, v4, v1 | @angular/core: Angular Template and Dynamic Component Namespace Bypass leading t |\n| @angular/core | moderate | CVE-2026-88057 | v5, v4, v3, v2, v1 | Angular: Sanitization bypass via directive host bindings on concrete host elemen |\n| @hono/node-server | moderate | CVE-2026-39406 | v2 | @hono/node-server: Middleware bypass via repeated slashes in serveStatic |\n| @hono/node-server | moderate | GHSA-frvp-7c67-39w9 | v3, v2 | Node.js Adapter for Hono: Path traversal in `serve-static` on Windows via encode |\n| @hono/node-server | moderate | CVE-2026-118663 | v5, v4, v3 | @hono/node-server: `serveStatic` decodes the request path a second time, leading |\n| @humanfs/node | moderate | GHSA-p498-v437-472g | v3 | humanfs: Recursive copy follows symlinked files and copies data from outside the |\n| @modelcontextprotocol/sdk | moderate | CVE-2026-111771 | v5, v4, v3, v2 | MCP TypeScript SDK: Server bearer authentication accepted tokens issued for anot |\n| @modelcontextprotocol/sdk | moderate | CVE-2026-111769 | v5, v4, v3, v2 | MCP TypeScript client SDK: HTTP client transports and OAuth requests followed cr |\n| @opentelemetry/core | moderate | CVE-2026-54285 | v1 | OpenTelemetry Core: Unbounded memory allocation in W3C Baggage propagation |\n| @opentelemetry/instrumentation-knex | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @opentelemetry/instrumentation-mongoose | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @opentelemetry/instrumentation-mysql | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @opentelemetry/instrumentation-mysql2 | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @opentelemetry/instrumentation-pg | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @opentelemetry/instrumentation-tedious | moderate | CVE-2026-104872 | v1 | Multiple @opentelemetry/instrumentation-* packages expose database username via |\n| @sigstore/core | moderate | CVE-2026-48758 | v3, v2, v1 | @sigstore/core has DSSE payloadType type-binding failure |\n| @xmldom/xmldom | moderate | CVE-2026-83610 | v5, v4 | xmldom: XML fragment injection via invalid EntityReference.nodeName during requi |\n| @xmldom/xmldom | moderate | CVE-2026-83611 | v5, v4 | xmldom: Parser silently accepts a not-well-formed end tag whose name is followed |\n| adm-zip | moderate | CVE-2026-76845 | v5, v4, v2 | adm-zip extraction follows destination symlinks, allowing arbitrary file overwri |\n| adm-zip | moderate | GHSA-p634-w6r4-rjp2 | v5, v4, v2 | adm-zip: Duplicate ZIP entry names: getEntry() and extractAllTo() resolve to dif |\n| adm-zip | moderate | GHSA-c6fg-446q-cg94 | v5, v4, v2 | adm-zip: getDataAsync() bypasses the maxOutputLength size guard enforced by the |\n| ajv | moderate | CVE-2025-69873 | v3, v2 | ajv has ReDoS when using `$data` option |\n| axios | moderate | CVE-2026-101908 | v5, v4, v3, v2, v1 | Axios: Prototype pollution gadget in fetch adapter can alter outbound requests |\n| axios | moderate | CVE-2026-101902 | v5, v4, v3, v2, v1 | Axios: Prototype-Pollution Gadget in the Default Instance Allows Inherited Objec |\n| axios | moderate | CVE-2026-101904 | v5, v4, v3, v2, v1 | Axios: Header Injection via Inherited headers After Minimal Interceptor |\n| axios | moderate | CVE-2026-101900 | v5, v4, v3, v2, v1 | Axios: Fetch Adapter Header Injection via Inherited FormData getHeaders |\n| axios | moderate | CVE-2026-101899 | v5, v4, v2, v1 | Axios: CIDR-form NO_PROXY entries are ignored, causing proxy exclusion bypass fo |\n| axios | moderate | CVE-2025-62718 | v3 | Axios has a NO_PROXY Hostname Normalization Bypass that Leads to SSRF |\n| axios | moderate | CVE-2026-42041 | v3 | Axios: Authentication Bypass via Prototype Pollution Gadget in `validateStatus` |\n| axios | moderate | CVE-2026-42044 | v3 | Axios: Invisible JSON Response Tampering via Prototype Pollution Gadget in `pars |\n| axios | moderate | CVE-2026-42037 | v3 | Axios: CRLF Injection in multipart/form-data body via unsanitized blob.type in f |\n| axios | moderate | CVE-2026-42038 | v3 | Axios: no_proxy bypass via IP alias allows SSRF |\n| axios | moderate | CVE-2026-42034 | v3 | Axios' HTTP adapter-streamed uploads bypass maxBodyLength when maxRedirects: 0 |\n| axios | moderate | CVE-2026-42036 | v3 | Axios: HTTP adapter streamed responses bypass maxContentLength |\n| axios | moderate | CVE-2026-42042 | v3 | Axios: XSRF Token Cross-Origin Leakage via Prototype Pollution Gadget in `withXS |\n| axios | moderate | CVE-2026-40175 | v3 | Axios has Unrestricted Cloud Metadata Exfiltration via Header Injection Chain |\n| axios | moderate | CVE-2026-42039 | v3 | Axios: unbounded recursion in toFormData causes DoS via deeply nested request da |\n| axios | moderate | CVE-2026-44490 | v3 | axios has DoS & Header Injection via Prototype Pollution Read-Side Gadgets in ax |\n| axios | moderate | CVE-2026-67316 | v3 | Axios: Prototype pollution gadgets can alter axios request construction |\n| axios | moderate | CVE-2026-67312 | v3 | Axios: Deep formToJSON Key Recursion Can Cause Denial of Service |\n| axios | moderate | CVE-2026-67319 | v3 | Axios: Nested axios option objects can consume polluted prototype values |\n| axios | moderate | CVE-2026-67317 | v3 | Axios: Fetch adapter `ReadableStream` uploads bypass `maxBodyLength` |\n| axios | moderate | CVE-2026-67313 | v3 | Axios: Excessive recursion in formDataToJSON can cause denial of service |\n| baseline-browser-mapping | moderate | CVE-2026-45819 | v3, v1 | baseline-browser-mapping process termination on invalid input causes denial of s |\n| brace-expansion | moderate | CVE-2026-45149 | v3, v2, v1 | brace-expansion: Large numeric range defeats documented `max` DoS protection |\n| brace-expansion | moderate | CVE-2026-102277 | v5, v4, v3, v2, v1 | brace-expansion: Quadratic-time expansion of the `{a},b}` rewrite causes CPU den |\n| brace-expansion | moderate | CVE-2026-33750 | v3, v2 | brace-expansion: Zero-step sequence causes process hang and memory exhaustion |\n| colord | moderate | CVE-2026-85062 | v3, v2, v1 | Colord: Slow rejection of oversized malformed color strings |\n| decode-uri-component | moderate | CVE-2026-45822 | v3, v2, v1 | decode-uri-component: Denial of service via exponential decoding of malformed pe |\n| dompurify | moderate | GHSA-55q2-fjhq-7xh7 | v1 | DOMPurify: IN_PLACE hook removal leaves a detached subtree executable, causing X |\n| ejs | moderate | CVE-2024-33883 | v2 | ejs lacks certain pollution protection |\n| esbuild | moderate | GHSA-67mh-4wv8-2f99 | v2 | esbuild enables any website to send any requests to the development server and r |\n| fast-uri | moderate | CVE-2026-86472 | v5, v4, v3, v2, v1 | fast-uri vulnerable to inconsistent host case normalization via percent-encoded |\n| fast-uri | moderate | CVE-2026-110306 | v5, v4, v3, v2, v1 | fast-uri vulnerable to URI scheme spoofing via percent-encoded scheme decoding |\n| fast-uri | moderate | CVE-2026-110180 | v5, v4, v1 | fast-uri vulnerable to host confusion via unchecked WHATWG host canonicalization |\n| fast-xml-parser | moderate | CVE-2026-33349 | v3, v2 | Entity Expansion Limits Bypassed When Set to Zero Due to JavaScript Falsy Evalua |\n| fast-xml-parser | moderate | CVE-2026-41650 | v3, v2 | fast-xml-parser XMLBuilder: XML Comment and CDATA Injection via Unescaped Delimi |\n| fastify | moderate | CVE-2026-18504 | v3 | fastify vulnerable to schema validation bypass via root primitive coercion misma |\n| fastify | moderate | CVE-2026-16732 | v3 | fastify vulnerable to X-Forwarded-* spoofing under trustProxy hop-count |\n| fastify | moderate | CVE-2026-92081 | v3 | fastify vulnerable to Denial of Service via unhandled exception on HTTP/2 traile |\n| file-type | moderate | CVE-2026-31808 | v5, v4 | file-type affected by infinite loop in ASF parser on malformed input with zero-s |\n| glob | moderate | CVE-2026-118773 | v5, v4, v3, v2, v1 | Glob: AbortSignal cancellation bypass allows post-timeout filesystem traversal |\n| handlebars | moderate | CVE-2026-33916 | v3, v1 | Handlebars.js has Prototype Pollution Leading to XSS through Partial Template In |\n| handlebars | moderate | GHSA-7rx3-28cr-v5wh | v3, v1 | Handlebars.js has a Prototype Method Access Control Gap via Missing __lookupSett |\n| handlebars | moderate | CVE-2026-106444 | v5, v4, v3, v2, v1 | Handlebars: JavaScript Injection via Unsafe Inline Embedding of Precompiled Temp |\n| hono | moderate | CVE-2026-29086 | v2 | Hono Vulnerable to Cookie Attribute Injection via Unsanitized domain and path in |\n| hono | moderate | CVE-2026-29085 | v2 | Hono Vulnerable to SSE Control Field Injection via CR/LF in writeSSE() |\n| hono | moderate | CVE-2026-39410 | v2 | Hono: Non-breaking space prefix bypass in cookie name handling in getCookie() |\n| hono | moderate | CVE-2026-39408 | v2 | Hono: Path traversal in toSSG() allows writing files outside the output director |\n| hono | moderate | CVE-2026-39407 | v2 | Hono: Middleware bypass via repeated slashes in serveStatic |\n| hono | moderate | CVE-2026-39409 | v2 | Hono has incorrect IP matching in ipRestriction() for IPv4-mapped IPv6 addresses |\n| hono | moderate | CVE-2026-44458 | v2 | Hono has CSS Declaration Injection via Style Object Values in JSX SSR |\n| hono | moderate | CVE-2026-44457 | v2 | Hono's Cache Middleware ignores Vary: Authorization / Vary: Cookie leading to cr |\n| hono | moderate | CVE-2026-44456 | v2 | Hono: bodyLimit() can be bypassed for chunked / unknown-length requests |\n| hono | moderate | CVE-2026-44455 | v2 | hono/jsx has Unvalidated JSX Tag Names that May Allow HTML Injection |\n| hono | moderate | CVE-2026-47674 | v2 | Hono: IP Restriction bypasses static deny rules for non-canonical IPv6 |\n| hono | moderate | CVE-2026-47675 | v2 | Hono: Cookie helper does not sanitize sameSite and priority, allowing Set-Cookie |\n| hono | moderate | CVE-2026-47673 | v2 | Hono: JWT middleware accepts any Authorization scheme, not only Bearer |\n| hono | moderate | CVE-2026-47676 | v2 | Hono: app.mount() strips mount prefix using undecoded path, causing incorrect ro |\n| hono | moderate | CVE-2026-56761 | v2 | hono Improperly Handles JSX Attribute Names Allows HTML Injection in hono/jsx SS |\n| hono | moderate | CVE-2026-54288 | v2 | hono: Body Limit Middleware can be bypassed on AWS Lambda by understating `Conte |\n| hono | moderate | CVE-2026-54289 | v2 | hono: Lambda@Edge adapter keeps only the last value of a repeated request header |\n| hono | moderate | CVE-2026-54286 | v2 | hono: Path traversal in `serve-static` on Windows via encoded backslash (`%5C`) |\n| hono | moderate | CVE-2026-54287 | v2 | hono: AWS Lambda adapter merges multiple `Set-Cookie` headers into one value, dr |\n| hono | moderate | CVE-2026-59897 | v3, v2 | Hono: API Gateway v1 adapter can drop a distinct repeated request header value d |\n| hono | moderate | CVE-2026-59895 | v3, v2 | Hono: Server-Side XSS via JSX Escaping Bypass in cx() Utility |\n| hono | moderate | CVE-2026-69207 | v3, v2 | Hono: ReDoS in CORS middleware via Access-Control-Request-Headers |\n| hono | moderate | CVE-2026-71850 | v3, v2 | Hono: `memo()` retains SSR output across requests, leading to cross-user data di |\n| hono | moderate | CVE-2026-84365 | v3, v2 | Hono: Incomplete fix for CVE-2026-39408: `toSSG()` still writes files outside th |\n| hono | moderate | CVE-2026-84364 | v3, v2 | Hono: Unbounded dot-notation nesting in `parseBody()` can cause memory exhaustio |\n| hono | moderate | CVE-2026-84363 | v3, v2 | Hono: Query parser reads parameters after the URL fragment, causing cache-key an |\n| hono | moderate | CVE-2026-56762 | v2 | Hono missing validation of cookie name on write path in setCookie() |\n| hono | moderate | CVE-2026-93981 | v3, v2 | hono/jsx renders plain strings unescaped in boundary components, leading to XSS |\n| hono | moderate | CVE-2026-56763 | v2 | Hono vulnerable to Prototype Pollution possible through **proto** key allowed in |\n| hono | moderate | CVE-2026-59896 | v3 | hono/jsx does not isolate context per request, leading to cross-request data dis |\n| hono | moderate | CVE-2026-71848 | v3 | Hono: Algorithmic Complexity DoS in Language Middleware |\n| hono | moderate | CVE-2026-111757 | v3 | Hono: `serveStatic` decodes the request path a second time, leading to bypass of |\n| http-proxy-middleware | moderate | CVE-2026-55602 | v3, v2 | http-proxy-middleware `router` host+path substring matching allows Host-header-d |\n| ip-address | moderate | CVE-2026-101913 | v5, v4, v3, v2, v1 | ip-address: Address6.isLinkLocal() recognizes fe80::/64 rather than fe80::/10, a |\n| ip-address | moderate | CVE-2026-101910 | v5, v4, v3, v1 | ip-address: no classifier recognizes the NAT64 local-use range 64:ff9b:1::/48, a |\n| ip-address | moderate | CVE-2026-101912 | v5, v4, v3, v2, v1 | ip-address: isInSubnet() and isHostInSubnet() compare addresses of different fam |\n| ip-address | moderate | CVE-2026-101911 | v5, v4, v3, v2, v1 | ip-address: Address6 builds a parse diagnostic proportional to the input with no |\n| ip-address | moderate | CVE-2026-111997 | v5, v4, v3, v2, v1 | ip-address: Address6 matches a zone identifier in quadratic time ahead of its le |\n| ip-address | moderate | CVE-2026-42338 | v2 | ip-address has XSS in Address6 HTML-emitting methods |\n| ip-address | moderate | CVE-2026-69198 | v3 | ip-address: a CIDR suffix on the parsed address suppresses special-use classific |\n| ip-address | moderate | CVE-2026-54272 | v3 | ip-address: misclassification of IPv4-mapped/NAT64 IPv6 addresses can bypass SSR |\n| js-yaml | moderate | CVE-2025-64718 | v2 | js-yaml has prototype pollution in merge (<<) |\n| js-yaml | moderate | CVE-2026-53550 | v3, v2 | JS-YAML: Quadratic-complexity DoS in merge key handling via repeated aliases |\n| launch-editor | moderate | CVE-2026-112943 | v5, v4, v3, v2, v1 | launch-editor: escapeCmdArgs() omits % escaping on Windows |\n| launch-editor | moderate | CVE-2026-112944 | v5, v4, v3, v2, v1 | launch-editor: Editor CLI flag misinterpretation causing arbitrary command execu |\n| launch-editor | moderate | CVE-2026-53632 | v3, v2 | launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows |\n| locutus | moderate | CVE-2026-33993 | v3, v2, v1 | Locutus has Prototype Pollution via **proto** Key Injection in unserialize() |\n| locutus | moderate | CVE-2026-33994 | v2 | Locutus Prototype Pollution due to incomplete fix for CVE-2026-25521 |\n| lodash | moderate | CVE-2026-2950 | v3 | lodash vulnerable to prototype pollution via array-path bypass in `_.unset`, `_. |\n| markdown-it | moderate | GHSA-253c-mchw-3w2r | v3, v2, v1 | markdown-it linkify: true has two quadratic paths, so a few hundred KB of markdo |\n| micromatch | moderate | CVE-2024-4067 | v3, v2, v1 | Regular Expression Denial of Service (ReDoS) in micromatch |\n| minimatch | moderate | CVE-2026-118764 | v5, v4, v3, v2, v1 | minimatch has potential denial of service via globparts amplification |\n| node-forge | moderate | CVE-2026-118777 | v2 | Forge: Prototype Pollution in forge.http cookie handling via a malicious Set-Coo |\n| node-forge | moderate | CVE-2026-118778 | v2 | Forge: TLS client crash when the server sends no certificate |\n| node-forge | moderate | CVE-2026-119186 | v2 | Forge: AES-GCM authentication bypass via unvalidated tagLength option |\n| nx | moderate | CVE-2026-54753 | v3, v1 | `nx graph` dev server permissive CORS policy |\n| nx | moderate | CVE-2026-104853 | v3, v2, v1 | Nx: Path traversal in nx migrate package-migrations extraction |\n| path-to-regexp | moderate | CVE-2026-4923 | v2 | path-to-regexp vulnerable to Regular Expression Denial of Service via multiple w |\n| postcss | moderate | CVE-2026-41305 | v5, v4, v3, v2 | PostCSS has XSS via Unescaped </style> in its CSS Stringify Output |\n| postcss | moderate | CVE-2026-69153 | v5, v4, v3, v2 | PostCSS: incomplete fix of GHSA-6g55-p6wh-862q — attacker-controlled sourceMappi |\n| postcss-selector-parser | moderate | CVE-2026-104844 | v5, v4, v3, v2, v1 | PostCSS: Quadratic complexity in flat selector parsing allows CPU exhaustion |\n| protobufjs | moderate | CVE-2026-59876 | v3 | protobufjs: Text Format string map parsing can mutate returned map object protot |\n| protobufjs | moderate | CVE-2026-59877 | v3 | protobufjs: Denial of Service via infinite loop in .proto option parsing |\n| qs | moderate | CVE-2026-8723 | v3, v2, v1 | qs has a remotely triggerable DoS: qs.stringify crashes with TypeError on null/u |\n| qs | moderate | CVE-2026-82562 | v5, v4, v3, v2, v1 | qs array-limit bypass via bracket-key comma parsing |\n| qs | moderate | CVE-2026-82417 | v5, v4, v3, v2, v1 | qs: Denial of Service via Attacker Controlled isBuffer |\n| qs | moderate | CVE-2026-110816 | v5, v4, v3, v2, v1 | qs : qs.stringify with arrayFormat 'comma' throws an uncaught TypeError on array |\n| qs | moderate | CVE-2025-15284 | v2 | qs's arrayLimit bypass in its bracket notation allows DoS via memory exhaustion |\n| react-router-dom | moderate | CVE-2026-53668 | v1 | React Router: Open redirect leading to XSS |\n| serialize-javascript | moderate | CVE-2026-34043 | v5, v4, v3, v2, v1 | Serialize JavaScript has CPU Exhaustion Denial of Service via crafted array-like |\n| serialize-javascript | moderate | CVE-2024-11831 | v2 | Cross-site Scripting (XSS) in serialize-javascript |\n| seroval | moderate | CVE-2026-116582 | v5, v4, v2, v1 | Seroval: Script injection through RegExp sources in serialized output |\n| seroval | moderate | CVE-2026-116583 | v5, v4 | Seroval: Code injection through a typed array's own constructor property |\n| smol-toml | moderate | GHSA-v3rj-xjv7-4jmq | v3, v1 | smol-toml: Denial of Service via TOML documents containing thousands of consecut |\n| smol-toml | moderate | GHSA-r4xh-jqrq-34v2 | v3, v2, v1 | smol-toml: Quadratic-time parse() from parseKey rescanning to end of document on |\n| svgo | moderate | CVE-2026-84369 | v5, v4, v3, v2, v1 | SVGO: removeScripts incompletely sanitizes executable HTML in SVG foreignObject |\n| tar | moderate | CVE-2026-53655 | v3, v1 | node-tar applies PAX size override to intermediary GNU long-name/long-link heade |\n| tar | moderate | CVE-2026-59871 | v3, v1 | node-tar: Process crash via PAX numeric path type confusion |\n| tar | moderate | CVE-2026-59875 | v3, v1 | node-tar: Uncaught Exception DoS via NUL byte in PAX path/linkpath records |\n| undici | moderate | CVE-2026-85024 | v5, v4, v2 | undici vulnerable to Denial of Service via unhandled error in WebSocket permessa |\n| undici | moderate | CVE-2026-18149 | v3, v2 | undici vulnerable to Denial of Service via orphaned RetryHandler response body |\n| undici | moderate | CVE-2026-84890 | v3, v2 | undici vulnerable to Denial of Service via unbounded decompression of compressed |\n| undici | moderate | CVE-2026-84933 | v3, v2 | undici vulnerable to cross-user cookie disclosure via Set-Cookie caching in shar |\n| undici | moderate | CVE-2026-85014 | v3, v2 | undici vulnerable to Denial of Service via WebSocketStream unclean close |\n| undici | moderate | CVE-2026-109924 | v5, v4, v3, v2 | undici vulnerable to Denial of Service via unbounded memory in the EventSource p |\n| undici | moderate | CVE-2026-109841 | v5, v4, v3, v2 | undici vulnerable to Subresource Integrity bypass via non-lowercase algorithm to |\n| undici | moderate | CVE-2026-109932 | v5, v4, v3, v2 | undici WebSocket client vulnerable to Denial of Service via unbounded automatic |\n| undici | moderate | CVE-2026-87029 | v5, v4, v3, v2 | undici vulnerable to Denial of Service via unhandled exception in the decompress |\n| undici | moderate | CVE-2026-1525 | v3 | Undici has an HTTP Request/Response Smuggling issue |\n| undici | moderate | CVE-2026-1527 | v3 | Undici has CRLF Injection in undici via `upgrade` option |\n| undici | moderate | CVE-2026-9679 | v3 | undici vulnerable to HTTP header injection via Set-Cookie percent-decoding |\n| undici | moderate | CVE-2026-9678 | v3 | undici vulnerable to cross-user information disclosure via shared cache whitespa |\n| undici | moderate | CVE-2026-16728 | v3 | undici vulnerable to downstream response desynchronization via retry interceptor |\n| undici | moderate | CVE-2026-15157 | v3 | undici vulnerable to CRLF Injection via blob-like body 'type' property |\n| undici | moderate | CVE-2026-14643 | v3 | undici vulnerable to cross-user information disclosure via whitespace around equ |\n| undici | moderate | CVE-2026-16729 | v3 | undici vulnerable to cookie attribute injection via unsanitized domain and unpar |\n| uuid | moderate | CVE-2026-41907 | v5, v4, v3, v2 | uuid: Missing buffer bounds check in v3/v5/v6 when buf is provided |\n| vite | moderate | CVE-2026-39365 | v1 | Vite Vulnerable to Path Traversal in Optimized Deps `.map` Handling |\n| vite | moderate | CVE-2026-53632 | v3, v1 | launch-editor: NTLMv2 hash disclosure via UNC path handling on Windows |\n| vite | moderate | CVE-2026-112943 | v5, v4, v3, v2, v1 | launch-editor: escapeCmdArgs() omits % escaping on Windows |\n| vite | moderate | CVE-2026-112944 | v5, v4, v3, v2, v1 | launch-editor: Editor CLI flag misinterpretation causing arbitrary command execu |\n| vite | moderate | CVE-2026-112946 | v5, v4, v3, v2, v1 | Vite: Files outside `server.fs.allow` could be served when project paths match s |\n| vite | moderate | CVE-2026-53571 | v3, v1 | vite: `server.fs.deny` bypass on Windows alternate paths |\n| vite | moderate | CVE-2026-112947 | v2 | Vite: First 4 bytes of files outside of `server.fs` setting is exposed by `?vite |\n| webpack | moderate | CVE-2024-43788 | v2 | Webpack's AutoPublicPathRuntimeModule has a DOM Clobbering Gadget that leads to |\n| webpack-dev-server | moderate | CVE-2025-30360 | v2 | webpack-dev-server users' source code may be stolen when they access a malicious |\n| webpack-dev-server | moderate | CVE-2025-30359 | v2 | webpack-dev-server users' source code may be stolen when they access a malicious |\n| webpack-dev-server | moderate | CVE-2026-6402 | v2 | webpack-dev-server vulnerable to cross-origin source code exposure on non-HTTPS |\n| webpack-dev-server | moderate | CVE-2026-9595 | v2 | webpack-dev-server vulnerable to HMR WebSocket interception via permissive user |\n| webpack-dev-server | moderate | CVE-2026-14620 | v3, v2 | webpack-dev-server vulnerable to cross-site request forgery via internal develop |\n| webpack-dev-server | moderate | CVE-2026-14631 | v3, v2 | webpack-dev-server vulnerable to denial of service via a malformed Host or Origi |\n| websocket-driver | moderate | CVE-2026-54490 | v3, v2 | websocket-driver: Resource limit bypass via message compression |\n| ws | moderate | CVE-2026-45736 | v3, v2 | ws: Uninitialized memory disclosure |\n| yaml | moderate | CVE-2026-33532 | v3, v2, v1 | yaml is vulnerable to Stack Overflow via deeply nested YAML collections |\n| @babel/core | low | CVE-2026-49356 | v3, v2, v1 | @babel/core: Arbitrary File Read via sourceMappingURL Comment |\n| @grpc/grpc-js | low | CVE-2026-101915 | v3 | @grpc/grpc-js: The server transmits some error messages thrown by method handler |\n| @tootallnate/once | low | CVE-2026-3449 | v3, v2, v1 | @tootallnate/once vulnerable to Incorrect Control Flow Scoping |\n| axios | low | CVE-2026-42040 | v3 | Axios: Null Byte Injection via Reverse-Encoding in AxiosURLSearchParams |\n| body-parser | low | CVE-2026-12590 | v3, v2 | body-parser vulnerable to denial of service when invalid limit value silently di |\n| deepmerge | low | CVE-2026-93753 | v5, v4, v3, v2, v1 | deepmerge mergeObject() allows prototype poisoning of returned objects |\n| diff | low | CVE-2026-24001 | v5, v4, v3, v2 | jsdiff has a Denial of Service vulnerability in parsePatch and applyPatch |\n| dompurify | low | GHSA-6688-9rhm-gjv2 | v1 | DOMPurify: IN_PLACE returns a force-removed rawtext root whose text carries atta |\n| dompurify | low | GHSA-c6gr-qvv4-5v3f | v1 | DOMPurify: SMIL attributeName=href guard is skipped when PARSER_MEDIA_TYPE is ap |\n| fast-uri | low | CVE-2026-110095 | v5, v4, v3, v2, v1 | fast-uri vulnerable to improper path equivalence in relative reference normaliza |\n| fast-uri | low | CVE-2026-110725 | v5, v4, v3, v2, v1 | fast-uri vulnerable to scheme injection via an unescaped first-segment colon in |\n| fast-xml-parser | low | CVE-2026-27942 | v3, v2 | fast-xml-parser has stack overflow in XMLBuilder with preserveOrder |\n| handlebars | low | GHSA-442j-39wm-28r2 | v3, v1 | Handlebars.js has a Property Access Validation Bypass in container.lookup |\n| hono | low | GHSA-gq3j-xvxp-8hrf | v2 | Hono added timing comparison hardening in basicAuth and bearerAuth |\n| hono | low | CVE-2026-44459 | v2 | Hono has improper validation of NumericDate claims (exp, nbf, iat) in JWT verify |\n| hono | low | CVE-2026-71849 | v3, v2 | Hono: Proxy Helper does not remove response headers listed in the `Connection` h |\n| markdown-it | low | CVE-2026-111766 | v3, v2, v1 | markdown-it: Quadratic-time denial of service in inline HTML parsing with html e |\n| node-forge | low | CVE-2026-118775 | v2 | Forge: ASN.1 OID first arc truncation in asn1.oidToDer |\n| node-forge | low | CVE-2026-118781 | v2 | Forge: Denial of Service via infinite loop in BigInteger.modInverse() with negat |\n| node-forge | low | CVE-2026-118780 | v2 | Forge: verifyCertificateChain() removes trusted CA certificates with the same su |\n| postcss-selector-parser | low | CVE-2026-9358 | v3, v2, v1 | postcss-selector-parser allows denial of service through uncontrolled AST recurs |\n| qs | low | CVE-2026-2391 | v2 | qs's arrayLimit bypass in comma parsing allows denial of service |\n| serialize-javascript | low | CVE-2026-115897 | v5, v4, v3, v2, v1 | Serialize JavaScript: Cross-site scripting (XSS) via unescaped </script at the e |\n| undici | low | CVE-2026-18540 | v5, v4, v3, v2 | undici vulnerable to downstream response splitting via retry interceptor |\n| undici | low | CVE-2026-84947 | v3, v2 | undici vulnerable to response truncation via oversized chunked responses in the |\n| undici | low | CVE-2026-85008 | v3, v2 | undici vulnerable to caching and replay of unsafe HTTP method responses |\n| undici | low | CVE-2026-11525 | v3 | undici vulnerable to Set-Cookie SameSite attribute downgrade via permissive subs |\n| undici | low | CVE-2026-6733 | v3 | undici vulnerable to HTTP response queue poisoning via keep-alive socket reuse |\n| vite | low | CVE-2026-112945 | v5, v4, v3, v2, v1 | Vite: Cross origin script execution through Vite custom middleware |\n| webpack | low | CVE-2025-68458 | v2 | webpack buildHttp: allowedUris allow-list bypass via URL userinfo (@) leading to |\n| webpack | low | CVE-2025-68157 | v2 | webpack buildHttp HttpUriPlugin allowedUris bypass via HTTP redirects → SSRF + c |\n",
391
391
  "kind": "doc"
392
392
  },
393
393
  {
@@ -405,7 +405,7 @@
405
405
  "name": "FOCUS_PROPAGATION_CONCEPT",
406
406
  "description": "Beschreibt, wie der Focus von einer KoliBri-Komponente an das fokussierbare HTML5-Element in ihrem Shadow DOM delegiert wird.",
407
407
  "path": "docs/FOCUS_PROPAGATION_CONCEPT.md",
408
- "code": "# Focus Propagation Concept\n\nBeschreibt, wie der Focus von einer KoliBri-Komponente an das fokussierbare HTML5-Element in ihrem Shadow DOM delegiert wird.\n\n## Überblick\n\nKoliBri Web Components verwenden Shadow DOM für Style-Isolation. Ein `focus()` auf dem Host-Element fokussiert nicht automatisch das innere interaktive Element, deshalb leitet die Komponente den Focus programmatisch an das tatsächlich fokussierbare HTML5-Element weiter.\n\nDie zentrale Herausforderung: Bevor der Focus gesetzt werden kann, müssen die Adopted Style Sheets geladen und angewendet sein. Ohne diese Absicherung kann es zu Race Conditions kommen — der Focus wird auf ein Element gesetzt, das noch nicht vollständig gerendert ist.\n\nTechnisch kann ein früher `focus()` im Browser teilweise trotzdem funktionieren. Das ist jedoch nicht authentisch zum realen Nutzerverhalten: Interaktion soll erst auf final sichtbaren und stabil gerenderten Controls stattfinden. Für Tests bedeutet das: Kein Focus auf potenziell noch unsichtbare oder semantisch unvollständige Elemente. Deshalb wird `data-themed` als verbindliche Readiness-Bedingung verwendet.\n\n## Architektur\n\nDie Functional Component einer Komponente rendert das fokussierbare HTML5-Element direkt in den Shadow DOM der Komponente. Die Delegation hat deshalb genau eine Stufe:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Shadow Component: kol-button (shadow: true) │\n│ @Method() @delegateFocus('ctaRef') focus() │\n└─────────────────────────┬───────────────────────────────┘\n ↓ wartet auf data-themed, dann setFocus(ctaRef.el)\n┌─────────────────────────────────────────────────────────┐\n│ HTML5 Element: <button class=\"kol-button__interactive-element\"> │\n│ Tatsächlich fokussierbar │\n└─────────────────────────────────────────────────────────┘\n```\n\nDasselbe gilt für alle anderen interaktiven Komponenten, z. B. `kol-link` (`<a>`), `kol-input-text` (`<input>`) oder `kol-select` (`<select>`).\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Sortier-Buttons von `kol-table-stateless` oder die Buttons von `kol-pagination`), dann rendert sie deren Functional Component über ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/src/components/_skeleton/ARC42.md#embedded-components-items)). Ein eingebetteter Button ist kein eigenes Element und hat kein eigenes `focus()`. Der Browser fokussiert sein natives `<button>` direkt, per Tab-Navigation oder Klick. Das `focus()` der einbettenden Komponente zielt auf deren eigenes primäres Element.\n\n### Das `data-themed`-Attribut\n\nDas Theme-System setzt das `data-themed`-Attribut auf Shadow-Komponenten, sobald die Adopted Style Sheets geladen sind. Der Ablauf:\n\n1. **Theme-Registrierung:** Beim Bootstrapping werden Themes über `register()` aus dem `adopted-style-sheets`-Paket registriert (`packages/components/src/core/bootstrap.ts`).\n\n2. **Style-Anwendung:** Stencils `setMode()`-Callback wird für jede Komponente aufgerufen (`packages/components/src/global/script.ts`). Dort wird `setThemeStyle(elm, getThemeDetails(elm))` aufgerufen, um die Adopted Style Sheets in den Shadow DOM zu injizieren.\n\n3. **Markierung:** `setThemeStyle()` setzt nach erfolgreicher Style-Anwendung das `data-themed`-Attribut auf dem Host-Element.\n\n## Utility Functions\n\n### `delegateFocus(host, callback)` — `packages/components/src/utils/element-focus.ts`\n\nZentrale Focus-Delegations-Funktion für Shadow Components. Wartet auf die Theme-Bereitschaft des Host-Elements und führt dann die Focus-Callback-Funktion aus.\n\n```typescript\nexport async function delegateFocus(host: HTMLElement, callback: () => Promise<void>): Promise<void> {\n\ttry {\n\t\tif (!host.hasAttribute('data-themed')) {\n\t\t\tawait waitForThemed(host);\n\t\t}\n\t\tawait callback();\n\t} catch {\n\t\tthrow new Error(\n\t\t\t`The interactive element inside the KoliBri web component could not be focused. Try calling the focus method on the web component after a short delay again.`,\n\t\t);\n\t}\n}\n```\n\n**Parameter:**\n\n- `host` — Das Host-Element der Komponente\n- `callback` — Async Funktion, die `setFocus()` auf dem Ziel-Element aufruft\n\n**Verhalten:**\n\n1. Prüft, ob `data-themed` bereits gesetzt ist\n2. Falls nicht: wartet über `waitForThemed()` (MutationObserver) bis maximal 5 Sekunden\n3. Ruft dann den `callback` auf, der den eigentlichen Focus setzt\n4. Bei Fehler (Timeout oder Focus-Fehler): wirft einen benutzerfreundlichen Fehler\n\nDie Wartephase ist nicht nur technisch motiviert, sondern auch eine Qualitätsgrenze: Sie verhindert, dass Focus-Interaktionen in Tests oder in schneller Initialisierung auf UI-Zuständen stattfinden, die ein Nutzer so noch nicht sieht.\n\n### `setFocus(element, options?)` — `packages/components/src/utils/element-focus.ts`\n\nFokussiert ein HTML-Element durch wiederholte Versuche pro Animation Frame (vereinfacht dargestellt):\n\n```typescript\nexport async function setFocus(element: HTMLElement): Promise<void> {\n\tlet attempts = 0;\n\tdo {\n\t\tif (element) {\n\t\t\telement.focus({ preventScroll: true });\n\t\t}\n\t\tawait new Promise((r) => requestAnimationFrame(r));\n\t\tattempts++;\n\t} while (!isActiveElement(element) && attempts < MAX_FOCUS_ATTEMPTS);\n}\n```\n\n**Verhalten:**\n\n- Ruft `element.focus()` auf und prüft pro Animation Frame, ob das Element fokussiert ist\n- Maximal `MAX_FOCUS_ATTEMPTS` (10) Versuche\n- Nutzt `isActiveElement()` für korrekte Focus-Erkennung innerhalb von Shadow DOMs\n- Der Browser scrollt beim Fokussieren nicht (`preventScroll`). Enthalten die `KolFocusOptions` `behavior`, `block` oder `inline`, scrollt `setFocus` das Element danach selbst per `scrollIntoView`.\n- `afterFocus` wird aufgerufen, sobald das Element fokussiert ist, bei `behavior: 'smooth'` erst nach dem Ende des Scrollens\n\n### `isActiveElement(element)` (intern)\n\nPrüft, ob ein Element aktuell fokussiert ist. Berücksichtigt dabei korrekt die Shadow-DOM-Grenze.\n\n```typescript\nfunction isActiveElement(element: HTMLElement): boolean {\n\tconst root = element.getRootNode();\n\tif (root instanceof ShadowRoot) {\n\t\treturn root.activeElement === element;\n\t}\n\treturn document.activeElement === element;\n}\n```\n\n**Warum nötig:** `document.activeElement` zeigt bei fokussierten Elementen innerhalb eines Shadow DOM nur den Shadow Host, nicht das tatsächlich fokussierte Element. Daher wird `shadowRoot.activeElement` geprüft.\n\n### `waitForThemed(host)` — `packages/components/src/utils/element-themed.ts`\n\nWartet per MutationObserver darauf, dass das `data-themed`-Attribut auf dem Host-Element gesetzt wird.\n\n**Verhalten:**\n\n- Beobachtet Attribut-Änderungen auf dem Host-Element\n- Resolved sofort, wenn `data-themed` bereits gesetzt ist oder gesetzt wird\n- Timeout nach `MAX_TIMEOUT_DURATION` (5000 ms) mit Error\n\n## Umsetzung in Komponenten\n\n### Interface\n\nAlle fokussierbaren Komponenten implementieren das `FocusableElement`-Interface (`packages/components/src/schema/interfaces/FocusableElement.ts`):\n\n```typescript\nexport interface FocusableElement {\n\tfocus(options?: KolFocusOptions): Promise<void>;\n}\n```\n\n### Ref und Decorator\n\nDas Ziel-Element hält ein `CtaRef` aus `createCtaRef()`; die öffentliche Methode entsteht über einen Method-Decorator aus `packages/components/src/utils/element-interaction.ts`:\n\n```typescript\n@Component({ tag: 'kol-button', shadow: true })\nexport class KolButton extends BaseButtonWebComponent implements ButtonProps, FocusableElement {\n\t@Element() protected readonly host?: HTMLKolButtonElement;\n\n\t// In der Basisklasse: protected readonly ctaRef = createCtaRef<HTMLButtonElement>();\n\t// Die Functional Component setzt ihn am nativen Element: <button ref={ctaRef} …>\n\n\t@Method()\n\t@delegateFocus('ctaRef')\n\tpublic async focus(options?: KolFocusOptions): Promise<void> {}\n}\n```\n\n`createCtaRef(isInactive?)` nimmt optional ein Prädikat entgegen. Solange es `true` liefert, liest sich `ctaRef.el` als `undefined` und `focus()` tut nichts. So bleibt ein deaktiviertes Element ohne natives `disabled` (z. B. `<a>`) für die öffentliche Methode unerreichbar.\n\n### Die Decorators\n\n| Decorator | Verhalten |\n| ----------------------- | ---------------------------------------------------------------------------------------------------- |\n| `@delegateFocus('ref')` | Wartet über `delegateFocus` auf `data-themed` und fokussiert dann `ref.el` mit `setFocus`. Standard. |\n| `@directFocus('ref')` | Fokussiert `ref.el` mit `setFocus`, ohne auf `data-themed` zu warten (heute nur `kol-tree-item`). |\n\n**Wichtig:**\n\n- Der Decorator ersetzt den Methodenrumpf; die Methode selbst bleibt leer.\n- `setFocus` ist in beiden Fällen die eigentliche Focus-Funktion.\n- Alle `focus()`-Methoden sind `async` und geben `Promise<void>` zurück.\n- Der `@Method()`-Decorator macht die Methode auf dem Custom Element aufrufbar.\n",
408
+ "code": "# Focus Propagation Concept\n\nBeschreibt, wie der Focus von einer KoliBri-Komponente an das fokussierbare HTML5-Element in ihrem Shadow DOM delegiert wird.\n\n## Überblick\n\nKoliBri Web Components verwenden Shadow DOM für Style-Isolation. Ein `focus()` auf dem Host-Element fokussiert nicht automatisch das innere interaktive Element, deshalb leitet die Komponente den Focus programmatisch an das tatsächlich fokussierbare HTML5-Element weiter.\n\nDie zentrale Herausforderung: Bevor der Focus gesetzt werden kann, müssen die Adopted Style Sheets geladen und angewendet sein. Ohne diese Absicherung kann es zu Race Conditions kommen — der Focus wird auf ein Element gesetzt, das noch nicht vollständig gerendert ist.\n\nTechnisch kann ein früher `focus()` im Browser teilweise trotzdem funktionieren. Das ist jedoch nicht authentisch zum realen Nutzerverhalten: Interaktion soll erst auf final sichtbaren und stabil gerenderten Controls stattfinden. Für Tests bedeutet das: Kein Focus auf potenziell noch unsichtbare oder semantisch unvollständige Elemente. Deshalb wird `data-themed` als verbindliche Readiness-Bedingung verwendet.\n\n## Architektur\n\nDie Functional Component einer Komponente rendert das fokussierbare HTML5-Element direkt in den Shadow DOM der Komponente. Die Delegation hat deshalb genau eine Stufe:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ Shadow Component: kol-button (shadow: true) │\n│ @Method() @delegateFocus('ctaRef') focus() │\n└─────────────────────────┬───────────────────────────────┘\n ↓ wartet auf data-themed, dann setFocus(ctaRef.el)\n┌─────────────────────────────────────────────────────────┐\n│ HTML5 Element: <button class=\"kol-button__interactive-element\"> │\n│ Tatsächlich fokussierbar │\n└─────────────────────────────────────────────────────────┘\n```\n\nDasselbe gilt für alle anderen interaktiven Komponenten, z. B. `kol-link` (`<a>`), `kol-input-text` (`<input>`) oder `kol-select` (`<select>`).\n\n### Eingebettete Komponenten\n\nRendert eine Komponente eine andere Komponente in ihrem Shadow DOM (z. B. die Sortier-Buttons von `kol-table-stateless` oder die Buttons von `kol-pagination`), dann rendert sie deren Functional Component über ein Item (`createButtonItem`, `createLinkItem`, …, siehe [ARC42 – Embedded Components (Items)](../packages/components/docs/ARC42-SKELETON.md#embedded-components-items)). Ein eingebetteter Button ist kein eigenes Element und hat kein eigenes `focus()`. Der Browser fokussiert sein natives `<button>` direkt, per Tab-Navigation oder Klick. Das `focus()` der einbettenden Komponente zielt auf deren eigenes primäres Element.\n\n### Das `data-themed`-Attribut\n\nDas Theme-System setzt das `data-themed`-Attribut auf Shadow-Komponenten, sobald die Adopted Style Sheets geladen sind. Der Ablauf:\n\n1. **Theme-Registrierung:** Beim Bootstrapping werden Themes über `register()` aus dem `adopted-style-sheets`-Paket registriert (`packages/components/src/core/bootstrap.ts`).\n\n2. **Style-Anwendung:** Stencils `setMode()`-Callback wird für jede Komponente aufgerufen (`packages/components/src/global/script.ts`). Dort wird `setThemeStyle(elm, getThemeDetails(elm))` aufgerufen, um die Adopted Style Sheets in den Shadow DOM zu injizieren.\n\n3. **Markierung:** `setThemeStyle()` setzt nach erfolgreicher Style-Anwendung das `data-themed`-Attribut auf dem Host-Element.\n\n## Utility Functions\n\n### `delegateFocus(host, callback)` — `packages/components/src/utils/element-focus.ts`\n\nZentrale Focus-Delegations-Funktion für Shadow Components. Wartet auf die Theme-Bereitschaft des Host-Elements und führt dann die Focus-Callback-Funktion aus.\n\n```typescript\nexport async function delegateFocus(host: HTMLElement, callback: () => Promise<void>): Promise<void> {\n\ttry {\n\t\tif (!host.hasAttribute('data-themed')) {\n\t\t\tawait waitForThemed(host);\n\t\t}\n\t\tawait callback();\n\t} catch {\n\t\tthrow new Error(\n\t\t\t`The interactive element inside the KoliBri web component could not be focused. Try calling the focus method on the web component after a short delay again.`,\n\t\t);\n\t}\n}\n```\n\n**Parameter:**\n\n- `host` — Das Host-Element der Komponente\n- `callback` — Async Funktion, die `setFocus()` auf dem Ziel-Element aufruft\n\n**Verhalten:**\n\n1. Prüft, ob `data-themed` bereits gesetzt ist\n2. Falls nicht: wartet über `waitForThemed()` (MutationObserver) bis maximal 5 Sekunden\n3. Ruft dann den `callback` auf, der den eigentlichen Focus setzt\n4. Bei Fehler (Timeout oder Focus-Fehler): wirft einen benutzerfreundlichen Fehler\n\nDie Wartephase ist nicht nur technisch motiviert, sondern auch eine Qualitätsgrenze: Sie verhindert, dass Focus-Interaktionen in Tests oder in schneller Initialisierung auf UI-Zuständen stattfinden, die ein Nutzer so noch nicht sieht.\n\n### `setFocus(element, options?)` — `packages/components/src/utils/element-focus.ts`\n\nFokussiert ein HTML-Element durch wiederholte Versuche pro Animation Frame (vereinfacht dargestellt):\n\n```typescript\nexport async function setFocus(element: HTMLElement): Promise<void> {\n\tlet attempts = 0;\n\tdo {\n\t\tif (element) {\n\t\t\telement.focus({ preventScroll: true });\n\t\t}\n\t\tawait new Promise((r) => requestAnimationFrame(r));\n\t\tattempts++;\n\t} while (!isActiveElement(element) && attempts < MAX_FOCUS_ATTEMPTS);\n}\n```\n\n**Verhalten:**\n\n- Ruft `element.focus()` auf und prüft pro Animation Frame, ob das Element fokussiert ist\n- Maximal `MAX_FOCUS_ATTEMPTS` (10) Versuche\n- Nutzt `isActiveElement()` für korrekte Focus-Erkennung innerhalb von Shadow DOMs\n- Der Browser scrollt beim Fokussieren nicht (`preventScroll`). Enthalten die `KolFocusOptions` `behavior`, `block` oder `inline`, scrollt `setFocus` das Element danach selbst per `scrollIntoView`.\n- `afterFocus` wird aufgerufen, sobald das Element fokussiert ist, bei `behavior: 'smooth'` erst nach dem Ende des Scrollens\n\n### `isActiveElement(element)` (intern)\n\nPrüft, ob ein Element aktuell fokussiert ist. Berücksichtigt dabei korrekt die Shadow-DOM-Grenze.\n\n```typescript\nfunction isActiveElement(element: HTMLElement): boolean {\n\tconst root = element.getRootNode();\n\tif (root instanceof ShadowRoot) {\n\t\treturn root.activeElement === element;\n\t}\n\treturn document.activeElement === element;\n}\n```\n\n**Warum nötig:** `document.activeElement` zeigt bei fokussierten Elementen innerhalb eines Shadow DOM nur den Shadow Host, nicht das tatsächlich fokussierte Element. Daher wird `shadowRoot.activeElement` geprüft.\n\n### `waitForThemed(host)` — `packages/components/src/utils/element-themed.ts`\n\nWartet per MutationObserver darauf, dass das `data-themed`-Attribut auf dem Host-Element gesetzt wird.\n\n**Verhalten:**\n\n- Beobachtet Attribut-Änderungen auf dem Host-Element\n- Resolved sofort, wenn `data-themed` bereits gesetzt ist oder gesetzt wird\n- Timeout nach `MAX_TIMEOUT_DURATION` (5000 ms) mit Error\n\n## Umsetzung in Komponenten\n\n### Interface\n\nAlle fokussierbaren Komponenten implementieren das `FocusableElement`-Interface (`packages/components/src/schema/interfaces/FocusableElement.ts`):\n\n```typescript\nexport interface FocusableElement {\n\tfocus(options?: KolFocusOptions): Promise<void>;\n}\n```\n\n### Ref und Decorator\n\nDas Ziel-Element hält ein `CtaRef` aus `createCtaRef()`; die öffentliche Methode entsteht über einen Method-Decorator aus `packages/components/src/utils/element-interaction.ts`:\n\n```typescript\n@Component({ tag: 'kol-button', shadow: true })\nexport class KolButton extends BaseButtonWebComponent implements ButtonProps, FocusableElement {\n\t@Element() protected readonly host?: HTMLKolButtonElement;\n\n\t// In der Basisklasse: protected readonly ctaRef = createCtaRef<HTMLButtonElement>();\n\t// Die Functional Component setzt ihn am nativen Element: <button ref={ctaRef} …>\n\n\t@Method()\n\t@delegateFocus('ctaRef')\n\tpublic async focus(options?: KolFocusOptions): Promise<void> {}\n}\n```\n\n`createCtaRef(isInactive?)` nimmt optional ein Prädikat entgegen. Solange es `true` liefert, liest sich `ctaRef.el` als `undefined` und `focus()` tut nichts. So bleibt ein deaktiviertes Element ohne natives `disabled` (z. B. `<a>`) für die öffentliche Methode unerreichbar.\n\n### Die Decorators\n\n| Decorator | Verhalten |\n| ----------------------- | ---------------------------------------------------------------------------------------------------- |\n| `@delegateFocus('ref')` | Wartet über `delegateFocus` auf `data-themed` und fokussiert dann `ref.el` mit `setFocus`. Standard. |\n| `@directFocus('ref')` | Fokussiert `ref.el` mit `setFocus`, ohne auf `data-themed` zu warten (heute nur `kol-tree-item`). |\n\n**Wichtig:**\n\n- Der Decorator ersetzt den Methodenrumpf; die Methode selbst bleibt leer.\n- `setFocus` ist in beiden Fällen die eigentliche Focus-Funktion.\n- Alle `focus()`-Methoden sind `async` und geben `Promise<void>` zurück.\n- Der `@Method()`-Decorator macht die Methode auf dem Custom Element aufrufbar.\n",
409
409
  "kind": "doc"
410
410
  },
411
411
  {
@@ -414,7 +414,25 @@
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` rendert nur input-text; textarea validiert die Prop, gibt sie aber nicht an das `<textarea>` weiter (#10863).\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: #10863 (spellCheck), #11051 (`_adjustHeight` schrumpft nicht), #11052 (Zähler bei `_hasCounter`/`_maxLengthBehavior` zur Laufzeit), #11053 (`has-value` uneinheitlich), #11054 (devHint zu `_autoComplete`).\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 wie bisher nicht gerendert (#10863). 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.\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` ist als letzte `-wc`-Komponente ebenfalls entfernt (#11338).\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
+ "kind": "doc"
419
+ },
420
+ {
421
+ "id": "doc/HOWTO_COMPONENT_TESTS_VITEST",
422
+ "group": "docs",
423
+ "name": "HOWTO_COMPONENT_TESTS_VITEST",
424
+ "description": "This guide shows how to test application components that use KoliBri with Vitest and Testing Library, without a browser and without mocking KoliBri. The tests render the real web components, operate them like a user and assert on the result.",
425
+ "path": "docs/HOWTO_COMPONENT_TESTS_VITEST.md",
426
+ "code": "# How to simulate user input on KoliBri components in Vitest\n\nThis guide shows how to test application components that use KoliBri with Vitest and\n[Testing Library](https://testing-library.com/), without a browser and without mocking KoliBri.\nThe tests render the real web components, operate them like a user and assert on the result.\n\nAll patterns are executable examples in\n[`packages/samples/presentation/src/test`](../packages/samples/presentation/src/test) and run in CI.\n\n## When to use which test\n\n| Goal | Test type |\n| -------------------------------------------------------------------------- | -------------------------------------------- |\n| Your component reacts correctly to typing, clicking, selecting, submitting | Vitest component test (this guide) |\n| Layout, visual appearance, real focus order, screen reader output | E2E test in a browser (e.g. Playwright) |\n| Your wrapper only forwards props to a KoliBri tag | Optional: custom element stub (see examples) |\n\nhappy-dom computes no layout and no real tab order. Everything that depends on rendering stays an\nE2E concern; everything that depends on events and state works in Vitest.\n\n## Setup\n\n### Dependencies\n\n```bash\npnpm add -D vitest happy-dom @testing-library/react @testing-library/user-event @testing-library/jest-dom shadow-dom-testing-library\n```\n\nUse **happy-dom** as the test environment. It implements everything KoliBri uses natively:\nconstructable stylesheets with `adoptedStyleSheets` on `Document` and `ShadowRoot`, `ResizeObserver`,\n`MutationObserver` and the `HTMLDialogElement` methods.\n\n### `vitest.config.ts`\n\n```ts\nimport react from '@vitejs/plugin-react-swc';\nimport { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n\tplugins: [react()],\n\ttest: {\n\t\tenvironment: 'happy-dom',\n\t\tsetupFiles: ['./vitest.setup.ts'],\n\t},\n});\n```\n\n### `vitest.setup.ts`\n\n```ts\nimport '@testing-library/jest-dom/vitest';\nimport { register } from '@public-ui/components';\nimport { defineCustomElements } from '@public-ui/components/loader';\nimport { DEFAULT } from '@public-ui/theme-default';\nimport { cleanup, configure } from '@testing-library/react';\nimport { afterEach } from 'vitest';\nimport { applyHappyDomWorkarounds } from './happy-dom-workarounds';\n\napplyHappyDomWorkarounds();\n\nawait register(DEFAULT, defineCustomElements);\n\nconfigure({ asyncUtilTimeout: 5000 });\nafterEach(cleanup);\n```\n\n- **`register(theme, defineCustomElements)`** is the same call as in the application. Use the theme\n your application uses.\n- **`asyncUtilTimeout`**: Stencil loads each component lazily on its first use. The first `findBy*`\n query in a test file includes that load and can exceed the default timeout of 1000 ms.\n- **`afterEach(cleanup)`**: Testing Library unmounts automatically only with `globals: true`.\n Without cleanup, the components of earlier tests stay in the document and queries find several\n matches.\n\n### `happy-dom-workarounds.ts`\n\nCopy [`happy-dom-workarounds.ts`](../packages/samples/presentation/src/test/happy-dom-workarounds.ts)\ninto your project. It corrects two deviations of happy-dom from the CSS specification that otherwise\nkeep every KoliBri host element at `visibility: hidden`:\n\n1. `style.setProperty(name, null)` does not remove the property ([capricorn86/happy-dom#2100](https://github.com/capricorn86/happy-dom/issues/2100)).\n2. `visibility: inherit` from a stylesheet is ignored, so Stencil's `.hydrated { visibility: inherit }` has no effect ([capricorn86/happy-dom#2400](https://github.com/capricorn86/happy-dom/issues/2400)).\n\nRemove a correction when its issue is fixed. Without these corrections, `findByShadowRole` finds the inner elements only with `hidden: true` and\ncannot match them by accessible name.\n\n## Rules for tests\n\n### 1. Interact with the native element inside the shadow root\n\nEvery KoliBri component renders its native `<input>`, `<button>`, `<select>` or `<textarea>` into a\nshadow root. Events on the custom element itself (`<kol-button>`) do not reach the `_on` callbacks.\nQuery the native element with\n[shadow-dom-testing-library](https://github.com/konnorrogers/shadow-dom-testing-library), which\noffers every Testing Library query with a `Shadow` infix:\n\n```tsx\nimport { screen } from 'shadow-dom-testing-library';\n\nconst input = await screen.findByShadowRole('textbox', { name: 'Name' });\nconst button = await screen.findByShadowRole('button', { name: 'Save' });\nconst checkbox = await screen.findByShadowLabelText('Agree');\n```\n\nPrefer `findByShadowRole` with `name`: it asserts the accessible name as a side effect.\n\n### 2. Always wait for the component with `findBy*`\n\nCustom elements upgrade asynchronously. Use `findByShadow*` (or `vi.waitFor`) for the first query of a\ncomponent, never `getByShadow*`. Awaiting the inner element also guarantees that a test does not end\nwhile a component chunk is still loading.\n\n### 3. Simulate input with `userEvent`\n\n```tsx\nimport userEvent from '@testing-library/user-event';\n\nconst user = userEvent.setup();\nawait user.type(input, 'Ada'); // one input event per character\nawait user.click(button);\nawait user.selectOptions(select, 'Hamburg');\nawait user.keyboard('{Enter}');\n```\n\n`fireEvent` also works and sets a value with a single event (`input.value = 'Ada'; fireEvent.input(input)`).\n`userEvent` is closer to real usage and is the recommended default.\n\nKnown limitations of `userEvent` with shadow roots:\n\n| Call | Behavior | Alternative |\n| ------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| `user.clear(input)` | Throws \"could not be focused\": it checks `document.activeElement` | `user.type(input, 'new', { initialSelectionStart: 0, initialSelectionEnd: old.length })` |\n| `user.tab()` | Does not enter shadow roots | Call `focus()` on the KoliBri element or `user.click()` the inner element |\n\n`user.tab()` still moves focus **out** of a field, which triggers its `onChange`.\n\n### 4. Assert on results, not on implementation\n\n- Callbacks from `_on` receive `(event, value)`. Assert on `value`:\n\n ```tsx\n const onChange = vi.fn();\n render(<KolSelect _label=\"City\" _options={cities} _on={{ onChange }} />);\n await user.selectOptions(await screen.findByShadowLabelText('City'), 'Hamburg');\n expect(onChange.mock.lastCall?.[1]).toBe('hamburg');\n ```\n\n- The component methods `getValue()`, `focus()`, `showModal()` and `close()` are called on the custom\n element (`document.querySelector('kol-input-text')`).\n- A native `<select>` inside `kol-select` holds internal option indices. Assert on the callback value or\n on `getValue()`, not on `select.value`.\n- Output of your own component lives in the light DOM; use the regular `screen` queries for it.\n\n### 5. Example: application form\n\nThe examples use the React adapter `@public-ui/react-v19`. With another framework, render the\ncomponent with its Testing Library variant; the queries and `userEvent` calls stay the same.\n\n```tsx\nconst GreetingForm = ({ onSave }: { onSave: (name: string) => void }) => {\n\tconst [name, setName] = useState('');\n\treturn (\n\t\t<KolForm _on={{ onSubmit: () => onSave(name) }}>\n\t\t\t<KolInputText _label=\"Name\" _value={name} _on={{ onInput: (_event, value) => setName(value as string) }} />\n\t\t\t<KolButton _label=\"Save\" _type=\"submit\" />\n\t\t</KolForm>\n\t);\n};\n\ntest('saves the typed name', async () => {\n\tconst user = userEvent.setup();\n\tconst onSave = vi.fn();\n\trender(<GreetingForm onSave={onSave} />);\n\n\tawait user.type(await screen.findByShadowRole('textbox', { name: 'Name' }), 'Ada');\n\tawait user.click(await screen.findByShadowRole('button', { name: 'Save' }));\n\n\texpect(onSave).toHaveBeenCalledWith('Ada');\n});\n```\n\nPressing Enter in the input (`user.type(input, 'Ada{Enter}')`) submits the form as well.\n\n## Examples\n\n| File | Shows |\n| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |\n| [`app-form.spec.tsx`](../packages/samples/presentation/src/test/app-form.spec.tsx) | Application component with form, input and submit |\n| [`button-click.spec.tsx`](../packages/samples/presentation/src/test/button-click.spec.tsx) | Click, disabled state, changed `_on`, tag without adapter |\n| [`input-text.spec.tsx`](../packages/samples/presentation/src/test/input-text.spec.tsx) | Typing, `onInput`/`onChange`, replacing a value, `fireEvent` |\n| [`choice-inputs.spec.tsx`](../packages/samples/presentation/src/test/choice-inputs.spec.tsx) | Checkbox, select, single-select, textarea |\n| [`keyboard-focus.spec.tsx`](../packages/samples/presentation/src/test/keyboard-focus.spec.tsx) | Enter/Space, `focus()` |\n| [`dialog-modal.spec.tsx`](../packages/samples/presentation/src/test/dialog-modal.spec.tsx) | Component methods and `onClose` |\n| [`custom-element-stub.spec.tsx`](../packages/samples/presentation/src/test/custom-element-stub.spec.tsx) | Stub for pure wrapper tests |\n",
427
+ "kind": "doc"
428
+ },
429
+ {
430
+ "id": "doc/HOWTO_ENABLE_ADD_CALLBACK_EVENTS",
431
+ "group": "docs",
432
+ "name": "HOWTO_ENABLE_ADD_CALLBACK_EVENTS",
433
+ "description": "To add a new Callback Event to an existing component you need to go through these steps: For this HowTo we will take the dialog-component as example.",
434
+ "path": "docs/HOWTO_ENABLE_ADD_CALLBACK_EVENTS.md",
435
+ "code": "# Enabling/Adding of Callback Events for Components\n\nTo add a new Callback Event to an existing component you need to go through these steps:\nFor this HowTo we will take the dialog-component as example.\n\n## Adding the Callback Event to Component Props\n\nThe callback events available for the component are defined within [dialog.ts](../packages/components/src/schema/types/dialog.ts) or in our case more precisely [modal.ts](../packages/components/src/schema/types/modal.ts).\nIf the event you wish to add is not among the existing entries in [KolEvent](../packages/components/src/utils/events.ts), you need to define it there.\nIf your desired event already exists here you can move on.\n\n## Enable the Component to be able to trigger the callback\n\nThe triggerable events for each component are defined within its own callback file. So to enable the possibility of triggering the event for that specific component that event needs to be added here.\nE.g. [dialog-callbacks.ts](../packages/components/src/internal/props/dialog-callbacks.ts)\n\n## Ensure Quality through adding/adjusting tests\n\n### Add the new callback event to callback tests\n\nTo ensure there are neither more nor fewer callback events than desired, the existence of each component's callback events is tested.\nConsequently any new callback events need to be added within these tests.\n[callback-props.spec.ts](../packages/components/src/internal/props/callback-props.spec.ts).\n\n### Adding e2e test for the component\n\nIn addition, e2e tests are performed to verify that the behavior of each individual event functions as intended.\nTherefore, these tests must be adjusted if the behavior changes.\nE.g. [dialog.e2e.ts](../packages/components/src/components/dialog/dialog.e2e.ts)\n\n## Adjusting the component itself\n\nFinally, the component must be able to handle these events, this requires a modification to the component. You can either extend the behavior using an existing event handler or create a completely new one.\nE.g. [Dialog Component](../packages/components/src/components/dialog/base.tsx)\nKeep in mind that you might have to restrict/enable that event from bubbling through the elements.\n\n## Creating a new sample or adjusting existing ones\n\nFor explanatory purposes, it is recommended to add a new sample or modify existing ones to illustrate the new behavior of this component.\nE.g. [Dialog Samples](../packages/samples/react/src/components/dialog)\n",
418
436
  "kind": "doc"
419
437
  },
420
438
  {
@@ -448,9 +466,9 @@
448
466
  "id": "doc/KNOWN_ISSUES",
449
467
  "group": "docs",
450
468
  "name": "KNOWN_ISSUES",
451
- "description": "In Chrome on Windows, clicking outside an HTML input but inside a Web Component does not give focus to the input when it is empty. This issue sometimes does not occur if the input already contains a value. We suspect a focus propagation problem related to Web Component behavior.",
469
+ "description": "kol-table-stateful/kol-table-stateless (_ariaLabelledby) and the form fields (_ariaDetails) connect external elements across the Shadow DOM boundary via ARIA element reflection (ariaLabelledByElements/ariaDetailsElements), because plain IDREFs cannot cross that boundary. VoiceOver on macOS does not…",
452
470
  "path": "KNOWN_ISSUES.md",
453
- "code": "# Known Issues\n\n## General\n\n### Limited support for `aria-description` (WAI-ARIA 1.2)\n\n- `aria-description` was introduced with [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/#aria-description), but many assistive technologies have not yet adopted it and continue to rely solely on `aria-describedby` when presenting supplementary text. Components that accept `_ariaDescription` therefore keep rendering hidden fallback markup and set both attributes so older screen readers still expose the description.\n\n## select\n\n### All text inputs\n\nIn Chrome on Windows, clicking outside an HTML input but inside a Web Component does not give focus to the input when it is empty. This issue sometimes does not occur if the input already contains a value. We suspect a focus propagation problem related to Web Component behavior.\n\n[🐞 GitHub issue #7713](https://github.com/public-ui/kolibri/issues/7713)\n\n### NVDA spells out certain words instead of reading them\n\nIt has been observed that on a system with German locale, NVDA spells out certain English words such as \"selection\", instead of reading them properly.\n\n[🐞 GitHub issue #6898](https://github.com/public-ui/kolibri/issues/6898),\n[Stack Overflow](https://stackoverflow.com/questions/69091167/nvda-spells-words-where-it-shouldnt)\n\n### Text selection in Firefox\n\nIn Firefox, text selection when using Web Components does not work as expected. Highlighting and selecting text behaves inconsistently or fails.\n\n[🐞 GitHub issue #7761](https://github.com/public-ui/kolibri/issues/7761),\n[Mozilla Bug #1587724](https://bugzilla.mozilla.org/show_bug.cgi?id=1587724),\n[Mozilla Bug #1233594](https://bugzilla.mozilla.org/show_bug.cgi?id=1233594),\n[Mozilla Bug #1590379](https://bugzilla.mozilla.org/show_bug.cgi?id=1590379)\n\n## Components\n\n### kol-select\n\n- Disabled options in KolSelect affect the total count in some screen readers. When an option is set to `disabled: true`, it may still be included in the overall option count announced by assistive technology. Using `aria-hidden=\"true\"` on `<option>` is not conforming with WAI-ARIA and causes browser warnings, therefore it has been removed. As a result, screen readers might announce a higher number of available options than can actually be selected.\n\n[🐞 GitHub issue #7453](https://github.com/public-ui/kolibri/pull/7453)\n[🐞 GitHub issue #7920](https://github.com/public-ui/kolibri/pull/7920)\n\n### kol-input-color\n\nThe component InputColor is a wrapper for the native HTML element `<input type=\"color\">` which has accessibility problems:\n\n- With NVDA, the element is announced as \"clickable\" and not as an input element.\n- It's not possible to select a color using a screen reader.\n- **9.1.3.1h Labeling of form elements programmatically detectable:**\n The label is not announced by the screen reader. Since it reads linearly, no label is perceivable when `hideLabel` is used.\n- **9.1.3.2 Meaningful sequence:**\n When opening the color selection for \"Color with error,\" there is no output. It is not accessible via the Tab key, only with the arrow keys, making it very confusing for screen reader users.\n- **9.2.4.3 Logical keyboard navigation order:**\n The focus order for \"Color with error\" is very unusual. Users do not realize that they have to use arrow keys to enter. This is especially problematic since it is not visible on black.\n- **9.2.4.7 Clearly visible focus position:**\n The focus is not visible on the black color icon in \"Color with error.\"\n\nFor full accessibility, consider using predefined colors lists, e.g. using KolSelect or KolCheckbox.\n\n[🐞 GitHub issue #5549](https://github.com/public-ui/kolibri/issues/5549),\n[🐞 GitHub issue #7455](https://github.com/public-ui/kolibri/pull/7455)\n\n### kol-table-stateful and kol-table-stateless\n\n#### `aria-sort` changes sometimes not announced in NVDA\n\nWhen a table column changes its sort order (i.e. when its `aria-sort` attribute changes), screen readers announce this change automatically. For unknown reasons, this sometimes does not happen in NVDA.\n\n[🐞 GitHub issue (PR) #5780](https://github.com/public-ui/kolibri/pull/5780),\n[🐞 NVDA issue #10890](https://github.com/nvaccess/nvda/issues/10890),\n[🐞 NVDA issue #8132](https://github.com/nvaccess/nvda/issues/8132)\n\n#### Sticky headers\n\nSticky headers in tables are not supported at the moment, because `position: sticky` doesn't work together with `overflow: auto` on the table container, without introducing other drawbacks.\n\n[🐞 GitHub issue #7490](https://github.com/public-ui/kolibri/issues/7490),\n[CSSWG Drafts issue](https://github.com/w3c/csswg-drafts/issues/865),\n[Code sample (StackBlitz)](https://stackblitz.com/edit/stackblitz-starters-umfg2y7m)\n\n### kol-input-number and kol-input-date\n\n#### `readonly` not announced in NVDA\n\nThe components InputNumber and InputDate render their respective native HTML elements `<input type=\"number\">` and `<input type=\"date\">` which both support the attribute `readonly`. When focusing the element, it's expected that the `readonly` attribute is announced as part of the element description. This isn't the case for NVDA.\n\n[🐞 GitHub issue #5554](https://github.com/public-ui/kolibri/issues/5554) (For number),\n[🐞 GitHub issue #5749](https://github.com/public-ui/kolibri/issues/5749) (For date),\n[🐞 NVDA issue #13672](https://github.com/nvaccess/nvda/issues/13672)\n\n### kol-input-date\n\n#### VoiceOver reads date inputs with percentage in Google Chrome\n\nIn Google Chrome, when using VoiceOver with empty `date` input fields (no initial value), an unexpected percentage value is read aloud alongside the usual prompt.\n\nNotably, this issue does not occur with Windows Narrator, which handles empty date inputs correctly.\n\nThere is a bug report for this issue:\n\n[VoiceOver reads negative percent values for month, day, and year steppers in `<input type=\"date\">`](https://issuetracker.google.com/issues/361250561?pli=1)\n\n### kol-input-text\n\nThe `search` of this component is highly browser-dependent. For example, the close button is either shown or hidden depending on the browser. Accessibility is therefore not achieved.\n\n[🐞 GitHub issue #6307](https://github.com/public-ui/kolibri/issues/6307)\n\n### kol-select\n\n#### Screen reader only reads last selected option\n\nKolSelect is using native HTML `<select>`.\n\nWhen using KolSelect with the `multiple` property, the native HTML `<select>` may cause problems with screen readers. Often the entire selection is not read out, but only the last one. Therefore, the KolSelect has no full accessibility.\n\n#### Limited styling capabilities for `<select>` and `<option>` elements\n\n[Stackblitz example](https://stackblitz.com/edit/vitejs-vite-nthnce?file=src%2Fstyle.css)\n\nThe `<select>` element and its `<option>` tags offer limited styling options. Specifically, states such as \"selected\", \"focus\" or \"active\" cannot be reliably customized using CSS. This leads to challenges in meeting accessibility standards, especially in ensuring sufficient contrast ratios.\n\n**Impact**:\n\n- **Limited customization**: The visual state of dropdown options (e.g., on focus or selection) cannot be consistently customized across all browsers. This makes it difficult to create an accessible visual experience for all users.\n- **Browser-dependent rendering**: The appearance of the `<select>` element varies across browsers and operating systems, resulting in inconsistent user experiences.\n- **Contrast issues**: Since the contrast of the default dropdown rendering is controlled by the browser, it's not always possible to ensure WCAG-compliant contrast ratios, which may hinder readability for users with visual impairments.\n\n### kol-icon\n\n#### Firefox accessibility issue with `aria-label`\n\nThe use of `aria-label` or `aria-labelledby` on `<kol-icon>` or its nested elements does not work reliably in Firefox. Even applying these attributes directly to `<kol-icon>` has no effect, which points to a browser-specific issue with ARIA support in custom elements or shadow DOM contexts.\n\n##### Key points\n\n- The issue lies in Firefox's handling of ARIA attributes on custom web components or deeply nested elements.\n- This is not related to dynamic announcements (`aria-live`) but specifically to the inability of Firefox to process `aria-label` or `aria-labelledby` correctly in these cases.\n- The issue is browser-specific and does not consistently occur in Chrome, Edge, or Safari.\n\n##### Conclusion\n\nThis is a limitation in Firefox’s ARIA implementation. Until it is resolved, alternative strategies like visually hidden text near the element or redundant error messages should be used to ensure accessibility.\n\n[🐞 GitHub issue #7076](https://github.com/public-ui/kolibri/issues/7076),\n[🐞 GitHub issue #7119](https://github.com/public-ui/kolibri/issues/7119)\n\n### Toaster\n\n> **Deprecated** — The `kol-toast-container` component and `ToasterService` are deprecated and will be removed in the next major version. See [#8372](https://github.com/public-ui/kolibri/issues/8372) and [#9110](https://github.com/public-ui/kolibri/issues/9110). Use [`kol-alert`](./packages/components/src/components/alert) for inline notifications and [`kol-dialog`](./packages/components/src/components/dialog) for interactive messages instead.\n\n#### Why toast notifications are fundamentally inaccessible\n\nThe international accessibility community broadly agrees: the classic toast pattern — auto-dismissing, corner-positioned notifications — cannot be made fully WCAG-conformant without removing the traits that define it. The following issues are structural and cannot be resolved through ARIA attributes, focus management, or the Popover API alone.\n\n#### SC 2.2.1 – Timing Adjustable (Level A) — critical\n\nAuto-dismissing toasts set a time limit on content perception. WCAG requires users to be able to turn off, adjust, or extend time limits. A toast only avoids violating SC 2.2.1 if the same information is simultaneously available elsewhere (e.g. a new email visible in the inbox). When the toast is the sole information source and disappears automatically, it violates SC 2.2.1 at **Level A** — the lowest conformance threshold.\n\nThe W3C WCAG Working Group clarified this in [issue #1814](https://github.com/w3c/wcag/issues/1814).\n\n#### SC 4.1.3 – Status Messages (Level AA)\n\nToasts must be announced via ARIA live regions without moving focus. In practice:\n\n- The live region container must exist in the DOM **before** content is inserted. If container and content are injected simultaneously, most screen readers ignore the announcement.\n- **JAWS** does not re-announce identical messages — inserting the same text twice results in silence for the second occurrence.\n- **NVDA** may drop `polite` announcements under load.\n- **VoiceOver (iOS)** historically only handled `assertive` live regions reliably.\n\n#### SC 2.1.1 – Keyboard (Level A)\n\nInteractive elements inside toasts (close button, \"Undo\" links) must be keyboard-accessible — in a race against the auto-dismiss timer. For users who type slowly or rely on switch access or voice control, this race cannot be won.\n\n#### SC 2.4.3 – Focus Order (Level A)\n\nToast elements appended to the end of the DOM are barely reachable by keyboard users before they disappear automatically.\n\n#### SC 1.3.2 – Meaningful Sequence (Level A)\n\nToast markup at the beginning or end of the DOM has no logical relationship to the element that triggered it. The document order does not match the visual or semantic order.\n\n#### SC 1.4.4 / 1.4.10 – Resize Text / Reflow (Level AA)\n\nEnlarged text can cause toasts to overflow or cover content. Toasts that appear outside the visible viewport at 400% zoom are effectively invisible to users relying on screen magnification.\n\n#### SC 2.2.4 – Interruptions (Level AAA)\n\nToasts are unsolicited interruptions. `role=\"alert\"` literally interrupts the running screen reader output regardless of what the user is currently reading.\n\n#### The toast paradox\n\n> \"You can improve the accessibility of toasts by removing the traits that make them toasts.\"\n> — Adam Silver, [Can you make toast messages accessible?](https://adamsilver.io/blog/can-you-make-toast-messages-accessible/)\n\nEvery measure that makes a toast genuinely accessible transforms it into a different component:\n\n| Measure | Result |\n| ---------------------------------------- | --------------------------------------------- |\n| No auto-dismiss | → Persistent inline alert |\n| Focus moved into the toast | → Non-modal dialog |\n| Notification history | → Notification panel / landmark region |\n| Plain text only, no interactive elements | → ARIA live region (no longer a visual toast) |\n\n> \"If a notification contains an interactive element, it should not be a live region. And it should also not be a toast.\"\n> — Sara Soueidan, [Accessible Notifications with ARIA Live Regions](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/)\n\n#### Why the Popover API does not solve the structural problems\n\nAn exploratory implementation using the native Popover API (`popover=\"manual\"`) was developed on branch `claude/toast-popover-dialog-6ahi8`. It improves the technical infrastructure:\n\n- ✅ No more z-index conflicts — each toast is independently promoted to the browser Top Layer\n- ✅ Focus is returned to the triggering element when a toast is closed by the user\n- ✅ Auto-fired toasts (where the user never focused into the toast) do not disrupt existing focus\n\nThe structural accessibility problems remain unresolved:\n\n- ❌ SC 2.2.1 — auto-dismiss timing\n- ❌ SC 4.1.3 — ARIA live region inconsistencies across browser/screen reader combinations\n- ❌ SC 2.1.1 — keyboard race condition against the timer\n- ❌ Visibility under screen magnification\n\n#### How leading design systems decide\n\n| Design system | Decision |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **GOV.UK Design System** | No toast — Notification Banner (persistent) instead |\n| **U.S. Web Design System** | No toast — Alert + Site Alert instead |\n| **GitHub Primer** | Toast officially banned after moderated usability tests with disabled users: \"The tests showed significant problems that cannot be addressed with a sprinkling of ARIA.\" |\n| **Adobe Spectrum** | Toast with strict constraints: min. 5 s timeout, pause on hover/focus, F6 landmark navigation |\n| **Carbon (IBM) v11** | Split into non-interactive (`role=\"status\"`) and interactive (`role=\"alertdialog\"` with full focus management) |\n\n#### References\n\n- [Adrian Roselli — Defining Toast Messages](https://adrianroselli.com/2020/01/defining-toast-messages.html) — analysis of ~50 implementations, none passed a full WCAG audit\n- [Scott O'Hara — A Toast to Accessibility](https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html)\n- [Sara Soueidan — Accessible Notifications with ARIA Live Regions (Part 2)](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/)\n- [Adam Silver — Can you make toast messages accessible?](https://adamsilver.io/blog/can-you-make-toast-messages-accessible/)\n- [GitHub Primer — Accessible Notifications and Messages](https://primer.style/accessibility/patterns/accessible-notifications-and-messages/)\n- [TetraLogical — Why are my live regions not working?](https://tetralogical.com/blog/2024/05/01/why-are-my-live-regions-not-working/)\n- [W3C WCAG Understanding 2.2.1 — Timing Adjustable](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html)\n- [W3C WCAG Working Group Issue #1814](https://github.com/w3c/wcag/issues/1814)\n- [Carbon Design System — Notification Pattern](https://carbondesignsystem.com/patterns/notification-pattern/)\n",
471
+ "code": "# Known Issues\n\n## General\n\n### Limited support for `aria-description` (WAI-ARIA 1.2)\n\n- `aria-description` was introduced with [WAI-ARIA 1.2](https://www.w3.org/TR/wai-aria-1.2/#aria-description), but many assistive technologies have not yet adopted it and continue to rely solely on `aria-describedby` when presenting supplementary text. Components that accept `_ariaDescription` therefore keep rendering hidden fallback markup and set both attributes so older screen readers still expose the description.\n\n### VoiceOver does not announce ARIA element references (`_ariaLabelledby`, `_ariaDetails`)\n\n`kol-table-stateful`/`kol-table-stateless` (`_ariaLabelledby`) and the form fields (`_ariaDetails`) connect external elements across the Shadow DOM boundary via ARIA element reflection (`ariaLabelledByElements`/`ariaDetailsElements`), because plain IDREFs cannot cross that boundary. VoiceOver on macOS does not announce these references — and a native control experiment shows the gap is platform-side, not in KoliBri: a vanilla web component whose inner native `<input>` carries the external references via `ariaDetailsElements` stays as silent as the KoliBri fields. The DOM API itself exists in WebKit since Safari 16.4, but the announcement does not reach the user.\n\n- **Fallback:** `_label` and `_hint` work with every screen reader.\n- **Verify with:** NVDA or JAWS on Chromium, where element references are followed.\n- **Reproduce:** Sample route `input-text/aria-details` stacks the control group from plain native markup over `demo-input-light`/`demo-input-shadow` (native web components, see [demo-input-wc.ts](./packages/samples/react/src/@shared/demo-input-wc.ts)) to the KoliBri fields; `table/aria-labelledby` is the equivalent for the table.\n\n[Chromium issue 41469336](https://issues.chromium.org/issues/41469336),\n[WebKit bug #179723](https://bugs.webkit.org/show_bug.cgi?id=179723),\n[WebKit bug #233594](https://bugs.webkit.org/show_bug.cgi?format=multiple&id=233594),\n[Mozilla bug #1769586](https://bugzilla.mozilla.org/show_bug.cgi?id=1769586),\n[MDN: `ariaLabelledByElements`](https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaLabelledByElements),\n[Reference Target proposal (WICG)](https://github.com/WICG/webcomponents/issues/1111)\n\n### Screen reader support for `aria-details` is heavily fragmented (`_ariaDetails`)\n\nIndependent of the element reflection gap above, the `aria-details` attribute itself is barely usable with today's screen readers. A complete implementation must master three steps: announce the presence of details, read their content, and signal the end of the details region. No common browser/screen reader combination does this flawlessly (data from [a11ysupport.io](https://a11ysupport.io/tech/aria/aria-details_attribute), as of October 2026):\n\n| Screen reader + browser | Presence | Content | End | Verdict |\n| -------------------------------- | -------- | ------- | --- | --------------------------------------------------------------------------------- |\n| NVDA + Chrome / Edge / Firefox | ✅ | ✅ | ❌ | Partially usable — reads the content, but never signals where the details end |\n| JAWS + Chrome / Edge / Firefox | ✅ | ❌ | ✅ | Poor — announces \"details available\" but often does not read the content directly |\n| Orca + Firefox | ✅ | ✅ | ✅ | Complete — the only combination that fulfils all three steps stably |\n| VoiceOver + Safari (macOS / iOS) | ❌ | ❌ | ❌ | Ignored completely |\n| TalkBack + Chrome (Android) | ❌ | ❌ | ❌ | Ignored completely |\n| Narrator + Edge (Windows) | ❌ | ❌ | ❌ | Ignored completely |\n\nThe browsers mostly feed the attribute into the accessibility tree correctly; the gap is on the screen reader side. Unlike `aria-describedby`, `aria-details` references rich, navigable structures rather than a flat text string, and many screen readers cannot navigate that acoustically.\n\n**Recommendation:** never rely on `aria-details` alone. If the details flatten to a text string without loss of information, prefer `_hint` or `aria-describedby` instead. Otherwise, keep the details visible on the page — for example as a `<details>` disclosure or a keyboard-reachable link to the additional information.\n\n[a11ysupport.io: aria-details](https://a11ysupport.io/tech/aria/aria-details_attribute),\n[Scott O'Hara: aria-details](https://www.scottohara.me/blog/2018/11/08/aria-details.html),\n[MDN: aria-details](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details)\n\n## select\n\n### All text inputs\n\nIn Chrome on Windows, clicking outside an HTML input but inside a Web Component does not give focus to the input when it is empty. This issue sometimes does not occur if the input already contains a value. We suspect a focus propagation problem related to Web Component behavior.\n\n[🐞 GitHub issue #7713](https://github.com/public-ui/kolibri/issues/7713)\n\n### NVDA spells out certain words instead of reading them\n\nIt has been observed that on a system with German locale, NVDA spells out certain English words such as \"selection\", instead of reading them properly.\n\n[🐞 GitHub issue #6898](https://github.com/public-ui/kolibri/issues/6898),\n[Stack Overflow](https://stackoverflow.com/questions/69091167/nvda-spells-words-where-it-shouldnt)\n\n### Text selection in Firefox\n\nIn Firefox, text selection when using Web Components does not work as expected. Highlighting and selecting text behaves inconsistently or fails.\n\n[🐞 GitHub issue #7761](https://github.com/public-ui/kolibri/issues/7761),\n[Mozilla Bug #1587724](https://bugzilla.mozilla.org/show_bug.cgi?id=1587724),\n[Mozilla Bug #1233594](https://bugzilla.mozilla.org/show_bug.cgi?id=1233594),\n[Mozilla Bug #1590379](https://bugzilla.mozilla.org/show_bug.cgi?id=1590379)\n\n## Components\n\n### kol-select\n\n- Disabled options in KolSelect affect the total count in some screen readers. When an option is set to `disabled: true`, it may still be included in the overall option count announced by assistive technology. Using `aria-hidden=\"true\"` on `<option>` is not conforming with WAI-ARIA and causes browser warnings, therefore it has been removed. As a result, screen readers might announce a higher number of available options than can actually be selected.\n\n[🐞 GitHub issue #7453](https://github.com/public-ui/kolibri/pull/7453)\n[🐞 GitHub issue #7920](https://github.com/public-ui/kolibri/pull/7920)\n\n### kol-input-color\n\nThe component InputColor is a wrapper for the native HTML element `<input type=\"color\">` which has accessibility problems:\n\n- With NVDA, the element is announced as \"clickable\" and not as an input element.\n- It's not possible to select a color using a screen reader.\n- **9.1.3.1h Labeling of form elements programmatically detectable:**\n The label is not announced by the screen reader. Since it reads linearly, no label is perceivable when `hideLabel` is used.\n- **9.1.3.2 Meaningful sequence:**\n When opening the color selection for \"Color with error,\" there is no output. It is not accessible via the Tab key, only with the arrow keys, making it very confusing for screen reader users.\n- **9.2.4.3 Logical keyboard navigation order:**\n The focus order for \"Color with error\" is very unusual. Users do not realize that they have to use arrow keys to enter. This is especially problematic since it is not visible on black.\n- **9.2.4.7 Clearly visible focus position:**\n The focus is not visible on the black color icon in \"Color with error.\"\n\nFor full accessibility, consider using predefined colors lists, e.g. using KolSelect or KolCheckbox.\n\n[🐞 GitHub issue #5549](https://github.com/public-ui/kolibri/issues/5549),\n[🐞 GitHub issue #7455](https://github.com/public-ui/kolibri/pull/7455)\n\n### kol-table-stateful and kol-table-stateless\n\n#### `aria-sort` changes sometimes not announced in NVDA\n\nWhen a table column changes its sort order (i.e. when its `aria-sort` attribute changes), screen readers announce this change automatically. For unknown reasons, this sometimes does not happen in NVDA.\n\n[🐞 GitHub issue (PR) #5780](https://github.com/public-ui/kolibri/pull/5780),\n[🐞 NVDA issue #10890](https://github.com/nvaccess/nvda/issues/10890),\n[🐞 NVDA issue #8132](https://github.com/nvaccess/nvda/issues/8132)\n\n#### Sticky headers\n\nSticky headers in tables are not supported at the moment, because `position: sticky` doesn't work together with `overflow: auto` on the table container, without introducing other drawbacks.\n\n[🐞 GitHub issue #7490](https://github.com/public-ui/kolibri/issues/7490),\n[CSSWG Drafts issue](https://github.com/w3c/csswg-drafts/issues/865),\n[Code sample (StackBlitz)](https://stackblitz.com/edit/stackblitz-starters-umfg2y7m)\n\n### kol-input-number and kol-input-date\n\n#### `readonly` not announced in NVDA\n\nThe components InputNumber and InputDate render their respective native HTML elements `<input type=\"number\">` and `<input type=\"date\">` which both support the attribute `readonly`. When focusing the element, it's expected that the `readonly` attribute is announced as part of the element description. This isn't the case for NVDA.\n\n[🐞 GitHub issue #5554](https://github.com/public-ui/kolibri/issues/5554) (For number),\n[🐞 GitHub issue #5749](https://github.com/public-ui/kolibri/issues/5749) (For date),\n[🐞 NVDA issue #13672](https://github.com/nvaccess/nvda/issues/13672)\n\n### kol-input-date\n\n#### VoiceOver reads date inputs with percentage in Google Chrome\n\nIn Google Chrome, when using VoiceOver with empty `date` input fields (no initial value), an unexpected percentage value is read aloud alongside the usual prompt.\n\nNotably, this issue does not occur with Windows Narrator, which handles empty date inputs correctly.\n\nThere is a bug report for this issue:\n\n[VoiceOver reads negative percent values for month, day, and year steppers in `<input type=\"date\">`](https://issuetracker.google.com/issues/361250561?pli=1)\n\n### kol-input-text\n\nThe `search` of this component is highly browser-dependent. For example, the close button is either shown or hidden depending on the browser. Accessibility is therefore not achieved.\n\n[🐞 GitHub issue #6307](https://github.com/public-ui/kolibri/issues/6307)\n\n### kol-select\n\n#### Screen reader only reads last selected option\n\nKolSelect is using native HTML `<select>`.\n\nWhen using KolSelect with the `multiple` property, the native HTML `<select>` may cause problems with screen readers. Often the entire selection is not read out, but only the last one. Therefore, the KolSelect has no full accessibility.\n\n#### Limited styling capabilities for `<select>` and `<option>` elements\n\n[Stackblitz example](https://stackblitz.com/edit/vitejs-vite-nthnce?file=src%2Fstyle.css)\n\nThe `<select>` element and its `<option>` tags offer limited styling options. Specifically, states such as \"selected\", \"focus\" or \"active\" cannot be reliably customized using CSS. This leads to challenges in meeting accessibility standards, especially in ensuring sufficient contrast ratios.\n\n**Impact**:\n\n- **Limited customization**: The visual state of dropdown options (e.g., on focus or selection) cannot be consistently customized across all browsers. This makes it difficult to create an accessible visual experience for all users.\n- **Browser-dependent rendering**: The appearance of the `<select>` element varies across browsers and operating systems, resulting in inconsistent user experiences.\n- **Contrast issues**: Since the contrast of the default dropdown rendering is controlled by the browser, it's not always possible to ensure WCAG-compliant contrast ratios, which may hinder readability for users with visual impairments.\n\n### kol-icon\n\n#### Firefox accessibility issue with `aria-label`\n\nThe use of `aria-label` or `aria-labelledby` on `<kol-icon>` or its nested elements does not work reliably in Firefox. Even applying these attributes directly to `<kol-icon>` has no effect, which points to a browser-specific issue with ARIA support in custom elements or shadow DOM contexts.\n\n##### Key points\n\n- The issue lies in Firefox's handling of ARIA attributes on custom web components or deeply nested elements.\n- This is not related to dynamic announcements (`aria-live`) but specifically to the inability of Firefox to process `aria-label` or `aria-labelledby` correctly in these cases.\n- The issue is browser-specific and does not consistently occur in Chrome, Edge, or Safari.\n\n##### Conclusion\n\nThis is a limitation in Firefox’s ARIA implementation. Until it is resolved, alternative strategies like visually hidden text near the element or redundant error messages should be used to ensure accessibility.\n\n[🐞 GitHub issue #7076](https://github.com/public-ui/kolibri/issues/7076),\n[🐞 GitHub issue #7119](https://github.com/public-ui/kolibri/issues/7119)\n\n### Toaster\n\n> **Deprecated** — The `kol-toast-container` component and `ToasterService` are deprecated and will be removed in the next major version. See [#8372](https://github.com/public-ui/kolibri/issues/8372) and [#9110](https://github.com/public-ui/kolibri/issues/9110). Use [`kol-alert`](./packages/components/src/components/alert) for inline notifications and [`kol-dialog`](./packages/components/src/components/dialog) for interactive messages instead.\n\n#### Why toast notifications are fundamentally inaccessible\n\nThe international accessibility community broadly agrees: the classic toast pattern — auto-dismissing, corner-positioned notifications — cannot be made fully WCAG-conformant without removing the traits that define it. The following issues are structural and cannot be resolved through ARIA attributes, focus management, or the Popover API alone.\n\n#### SC 2.2.1 – Timing Adjustable (Level A) — critical\n\nAuto-dismissing toasts set a time limit on content perception. WCAG requires users to be able to turn off, adjust, or extend time limits. A toast only avoids violating SC 2.2.1 if the same information is simultaneously available elsewhere (e.g. a new email visible in the inbox). When the toast is the sole information source and disappears automatically, it violates SC 2.2.1 at **Level A** — the lowest conformance threshold.\n\nThe W3C WCAG Working Group clarified this in [issue #1814](https://github.com/w3c/wcag/issues/1814).\n\n#### SC 4.1.3 – Status Messages (Level AA)\n\nToasts must be announced via ARIA live regions without moving focus. In practice:\n\n- The live region container must exist in the DOM **before** content is inserted. If container and content are injected simultaneously, most screen readers ignore the announcement.\n- **JAWS** does not re-announce identical messages — inserting the same text twice results in silence for the second occurrence.\n- **NVDA** may drop `polite` announcements under load.\n- **VoiceOver (iOS)** historically only handled `assertive` live regions reliably.\n\n#### SC 2.1.1 – Keyboard (Level A)\n\nInteractive elements inside toasts (close button, \"Undo\" links) must be keyboard-accessible — in a race against the auto-dismiss timer. For users who type slowly or rely on switch access or voice control, this race cannot be won.\n\n#### SC 2.4.3 – Focus Order (Level A)\n\nToast elements appended to the end of the DOM are barely reachable by keyboard users before they disappear automatically.\n\n#### SC 1.3.2 – Meaningful Sequence (Level A)\n\nToast markup at the beginning or end of the DOM has no logical relationship to the element that triggered it. The document order does not match the visual or semantic order.\n\n#### SC 1.4.4 / 1.4.10 – Resize Text / Reflow (Level AA)\n\nEnlarged text can cause toasts to overflow or cover content. Toasts that appear outside the visible viewport at 400% zoom are effectively invisible to users relying on screen magnification.\n\n#### SC 2.2.4 – Interruptions (Level AAA)\n\nToasts are unsolicited interruptions. `role=\"alert\"` literally interrupts the running screen reader output regardless of what the user is currently reading.\n\n#### The toast paradox\n\n> \"You can improve the accessibility of toasts by removing the traits that make them toasts.\"\n> — Adam Silver, [Can you make toast messages accessible?](https://adamsilver.io/blog/can-you-make-toast-messages-accessible/)\n\nEvery measure that makes a toast genuinely accessible transforms it into a different component:\n\n| Measure | Result |\n| ---------------------------------------- | --------------------------------------------- |\n| No auto-dismiss | → Persistent inline alert |\n| Focus moved into the toast | → Non-modal dialog |\n| Notification history | → Notification panel / landmark region |\n| Plain text only, no interactive elements | → ARIA live region (no longer a visual toast) |\n\n> \"If a notification contains an interactive element, it should not be a live region. And it should also not be a toast.\"\n> — Sara Soueidan, [Accessible Notifications with ARIA Live Regions](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/)\n\n#### Why the Popover API does not solve the structural problems\n\nAn exploratory implementation using the native Popover API (`popover=\"manual\"`) was developed on branch `claude/toast-popover-dialog-6ahi8`. It improves the technical infrastructure:\n\n- ✅ No more z-index conflicts — each toast is independently promoted to the browser Top Layer\n- ✅ Focus is returned to the triggering element when a toast is closed by the user\n- ✅ Auto-fired toasts (where the user never focused into the toast) do not disrupt existing focus\n\nThe structural accessibility problems remain unresolved:\n\n- ❌ SC 2.2.1 — auto-dismiss timing\n- ❌ SC 4.1.3 — ARIA live region inconsistencies across browser/screen reader combinations\n- ❌ SC 2.1.1 — keyboard race condition against the timer\n- ❌ Visibility under screen magnification\n\n#### How leading design systems decide\n\n| Design system | Decision |\n| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| **GOV.UK Design System** | No toast — Notification Banner (persistent) instead |\n| **U.S. Web Design System** | No toast — Alert + Site Alert instead |\n| **GitHub Primer** | Toast officially banned after moderated usability tests with disabled users: \"The tests showed significant problems that cannot be addressed with a sprinkling of ARIA.\" |\n| **Adobe Spectrum** | Toast with strict constraints: min. 5 s timeout, pause on hover/focus, F6 landmark navigation |\n| **Carbon (IBM) v11** | Split into non-interactive (`role=\"status\"`) and interactive (`role=\"alertdialog\"` with full focus management) |\n\n#### References\n\n- [Adrian Roselli — Defining Toast Messages](https://adrianroselli.com/2020/01/defining-toast-messages.html) — analysis of ~50 implementations, none passed a full WCAG audit\n- [Scott O'Hara — A Toast to Accessibility](https://www.scottohara.me/blog/2019/07/08/a-toast-to-a11y-toasts.html)\n- [Sara Soueidan — Accessible Notifications with ARIA Live Regions (Part 2)](https://www.sarasoueidan.com/blog/accessible-notifications-with-aria-live-regions-part-2/)\n- [Adam Silver — Can you make toast messages accessible?](https://adamsilver.io/blog/can-you-make-toast-messages-accessible/)\n- [GitHub Primer — Accessible Notifications and Messages](https://primer.style/accessibility/patterns/accessible-notifications-and-messages/)\n- [TetraLogical — Why are my live regions not working?](https://tetralogical.com/blog/2024/05/01/why-are-my-live-regions-not-working/)\n- [W3C WCAG Understanding 2.2.1 — Timing Adjustable](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html)\n- [W3C WCAG Working Group Issue #1814](https://github.com/w3c/wcag/issues/1814)\n- [Carbon Design System — Notification Pattern](https://carbondesignsystem.com/patterns/notification-pattern/)\n",
454
472
  "kind": "doc"
455
473
  },
456
474
  {
@@ -467,7 +485,7 @@
467
485
  "name": "MIGRATION",
468
486
  "description": "New major versions of KoliBri are developed with the aim of simplifying maintenance and support and promoting further development.",
469
487
  "path": "MIGRATION.md",
470
- "code": "# Migration\n\n## Introduction\n\nNew major versions of KoliBri are developed with the aim of simplifying maintenance and support and promoting further development.\n\nThis means that components, features or functionalities may be removed and technological prerequisites created to promote future innovative change.\n\n- **Maintenance and care strategy:**\n\n We will always maintain the latest and previous major version of KoliBri. This means that we will fix bugs and close security gaps for these versions. For all other versions, we will no longer provide bug fixes or security updates without further notice.\n\n- **Further development:**\n\n We will always continue to develop the latest major version of KoliBri. This means that we will provide new features and functionalities for these versions. For all other versions, we will no longer provide any new features or functionalities without further ado.\n\n- **Save an executable version before migration:**\n\n Before the migration takes place, we recommend checking in an executable version so that there are no uncommitted changes to the source code to be migrated. This means that all changes can be easily tracked and checked during and after the migration.\n\n- **Migrationstool:**\n\n We provide a migration tool that generally supports the migration of source code with KoliBri. This tool is able to migrate most breaking changes automatically. Further information can be found in the [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n > [!NOTE]\n > The migration tool currently covers React projects (`.jsx`/`.tsx`), Vue single-file components (`.vue`), and HTML/XHTML template projects (for example Angular templates or vanilla custom elements).\n\n- **Help and feedback:**\n\n If there are any problems with the migration, we are happy to help. Please open an [Issue on GitHub](https://github.com/public-ui/kolibri/issues/new/choose).\n\n## Migration from version 1 to version 2\n\n### Notes on upgrading to version 2\n\n1. **New features in version 2 already available from version 1.7:**\n\n Most of the new features introduced in version 2 are already available from version 1.7 and higher. This means that applications based on version 1.7 or higher may already have the necessary functions to enable a smooth migration.\n\n2. **Removed properties, components and functionalities were already marked as obsolete in version 1.7 and higher:**\n\n All features, components and functionalities that were removed in version 2 were already marked as deprecated in version 1.7 and higher. So if you have regularly updated your code base, you should already be prepared to replace these elements.\n\n3. **Migration from version 1.7 minimizes potential changes:**\n\n A migration from version 1.7 and higher to version 2 will probably require the least adjustments. The likelihood of incompatibilities is low, as most changes and removals have already been marked as obsolete in previous versions.\n\n4. **Migration from version 1.4 is possible:**\n\n Although a migration from version 1.7 is recommended, it is also possible to migrate from version 1.4 to version 2. Please note, however, that this may require additional adjustments, as some of the necessary functions may only be available from version 1.7.\n\n5. **Note simplified registration:**\n\n We have simplified the modularization of KoliBri in version 1 and for version 2. The module `@public-ui/core` has been removed and the functionalities moved to the module `@public-ui/components`.\n\n```diff\n - import { register } from '@public-ui/core';\n + import { register } from '@public-ui/components';\n import { defineCustomElements } from '@public-ui/components/loader';\n import { MyTheme } from '...';\n await register(MyTheme, defineCustomElements);\n```\n\n### Breaking changes for version 2\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v2.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v2.md).\n\n### Breaking changes for version 3\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v3.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v3.md).\n\n### Breaking changes for version 4\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v4.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v4.md).\n\n## Perform migration\n\n> [!TIP]\n> We recommend carrying out the migration with the migration tool. This tool is able to migrate most breaking changes automatically. Further information can be found in the [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n### Migration with migration tool\n\n1. **Preparation:**\n\n The project is on an earlier version, all dependencies are installed, the project is executable and all changes are checked in and safely pushed.\n\n2. **Execute migration:**\n\n Execute the following command to perform the migration: `npx @public-ui/kolibri-cli migrate src`\n\n3. **Check migration:**\n\n Check the changes and run the application to make sure everything works as expected.\n\n### Perform migration manually\n\n1. **Preparation:**\n\n The project is on an earlier version, all dependencies are installed, the project is executable and all changes are checked in and safely pushed.\n\n2. **Perform migration:**\n\n Carry out the migration by making the breaking changes in the respective documentation.\n",
488
+ "code": "# Migration\n\n## Introduction\n\nNew major versions of KoliBri are developed with the aim of simplifying maintenance and support and promoting further development.\n\nThis means that components, features or functionalities may be removed and technological prerequisites created to promote future innovative change.\n\n- **Maintenance and care strategy:**\n\n We will always maintain the latest and previous major version of KoliBri. This means that we will fix bugs and close security gaps for these versions. For all other versions, we will no longer provide bug fixes or security updates without further notice.\n\n- **Further development:**\n\n We will always continue to develop the latest major version of KoliBri. This means that we will provide new features and functionalities for these versions. For all other versions, we will no longer provide any new features or functionalities without further ado.\n\n- **Save an executable version before migration:**\n\n Before the migration takes place, we recommend checking in an executable version so that there are no uncommitted changes to the source code to be migrated. This means that all changes can be easily tracked and checked during and after the migration.\n\n- **Migrationstool:**\n\n We provide a migration tool that generally supports the migration of source code with KoliBri. This tool is able to migrate most breaking changes automatically. Further information can be found in the [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n > [!NOTE]\n > The migration tool currently covers React projects (`.jsx`/`.tsx`), Vue single-file components (`.vue`), and HTML/XHTML template projects (for example Angular templates or vanilla custom elements).\n\n- **Help and feedback:**\n\n If there are any problems with the migration, we are happy to help. Please open an [Issue on GitHub](https://github.com/public-ui/kolibri/issues/new/choose).\n\n## Migration from version 1 to version 2\n\n### Notes on upgrading to version 2\n\n1. **New features in version 2 already available from version 1.7:**\n\n Most of the new features introduced in version 2 are already available from version 1.7 and higher. This means that applications based on version 1.7 or higher may already have the necessary functions to enable a smooth migration.\n\n2. **Removed properties, components and functionalities were already marked as obsolete in version 1.7 and higher:**\n\n All features, components and functionalities that were removed in version 2 were already marked as deprecated in version 1.7 and higher. So if you have regularly updated your code base, you should already be prepared to replace these elements.\n\n3. **Migration from version 1.7 minimizes potential changes:**\n\n A migration from version 1.7 and higher to version 2 will probably require the least adjustments. The likelihood of incompatibilities is low, as most changes and removals have already been marked as obsolete in previous versions.\n\n4. **Migration from version 1.4 is possible:**\n\n Although a migration from version 1.7 is recommended, it is also possible to migrate from version 1.4 to version 2. Please note, however, that this may require additional adjustments, as some of the necessary functions may only be available from version 1.7.\n\n5. **Note simplified registration:**\n\n We have simplified the modularization of KoliBri in version 1 and for version 2. The module `@public-ui/core` has been removed and the functionalities moved to the module `@public-ui/components`.\n\n```diff\n - import { register } from '@public-ui/core';\n + import { register } from '@public-ui/components';\n import { defineCustomElements } from '@public-ui/components/loader';\n import { MyTheme } from '...';\n await register(MyTheme, defineCustomElements);\n```\n\n### Breaking changes for version 2\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v2.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v2.md).\n\n### Breaking changes for version 3\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v3.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v3.md).\n\n### Breaking changes for version 4\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v4.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v4.md).\n\n### Breaking changes for version 5\n\nYou can find more information about Breaking Changes in the documentation [BREAKING_CHANGES.v5.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v5.md).\n\n## Perform migration\n\n> [!TIP]\n> We recommend carrying out the migration with the migration tool. This tool is able to migrate most breaking changes automatically. Further information can be found in the [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n### Migration with migration tool\n\n1. **Preparation:**\n\n The project is on an earlier version, all dependencies are installed, the project is executable and all changes are checked in and safely pushed.\n\n2. **Execute migration:**\n\n Execute the following command to perform the migration: `npx @public-ui/kolibri-cli migrate src`\n\n3. **Check migration:**\n\n Check the changes and run the application to make sure everything works as expected.\n\n### Perform migration manually\n\n1. **Preparation:**\n\n The project is on an earlier version, all dependencies are installed, the project is executable and all changes are checked in and safely pushed.\n\n2. **Perform migration:**\n\n Carry out the migration by making the breaking changes in the respective documentation.\n",
471
489
  "kind": "doc"
472
490
  },
473
491
  {
@@ -476,7 +494,7 @@
476
494
  "name": "MIGRATION.de",
477
495
  "description": "Neue Major-Versionen von KoliBri werden mit dem Ziel entwickelt, die Wartung und Pflege zu vereinfachen und Weiterentwicklung zu fördern.",
478
496
  "path": "MIGRATION.de.md",
479
- "code": "# Migration\n\n## Einleitung\n\nNeue Major-Versionen von KoliBri werden mit dem Ziel entwickelt, die Wartung und Pflege zu vereinfachen und Weiterentwicklung zu fördern.\n\nDies bedeutet, dass ggf. Komponenten, Eigenschaften oder Funktionalitäten entfernt werden und technologische Voraussetzungen geschaffen werden, um einen zukünftigen innovativen Wandel zu begünstigt.\n\n- **Wartungs- und Pflegestrategie:**<br/>\n Wir werden immer die neuste und die vorherige Major-Version von KoliBri pflegen. Dies bedeutet, dass wir für diese Versionen Fehler beheben und Sicherheitslücken schließen. Für alle anderen Versionen werden wir ohne Weiteres keine Fehlerbehebungen oder Sicherheitsupdates mehr bereitstellen.\n- **Weiterentwicklung:**<br/>\n Wir werden immer die neuste Major-Version von KoliBri weiterentwickeln. Dies bedeutet, dass wir für diese Versionen neue Features und Funktionalitäten bereitstellen. Für alle anderen Versionen werden wir ohne Weiteres keine neuen Features oder Funktionalitäten mehr bereitstellen.\n- **Vor der Migration einen lauffähigen Stand sichern:**<br/>\n Bevor die Migration erfolgt, empfehlen wir einen lauffähigen Stand einzuchecken und somit keine uncommiteten Änderungen auf dem zu migrierenden Quellcode zu haben. Während und nach der Migration können so alle Änderungen gut nachvollzogen und geprüft werden.\n- **Migrationstool:**<br/>\n Wir stellen ein Migrationstool bereit, welches generell die Migration von Quellcode mit KoliBri unterstützt. Dieses Tool ist in der Lage, die meisten Breaking Changes automatisch zu migrieren. Weitere Informationen finden Sie in der [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n > [!NOTE]\n > Das Migrationstool unterstützt aktuell React-Projekte (`.jsx`/`.tsx`), Vue-Single-File-Components (`.vue`) sowie HTML/XHTML-Template-Projekte (z. B. Angular-Templates oder Projekte mit nativen Custom Elements).\n- **Hilfe und Feedback:**<br/>\n Sollte es Probleme bei der Migration geben, stehen wir gerne zur Verfügung. Bitte eröffnen Sie ein [Issue auf GitHub](https://github.com/public-ui/kolibri/issues/new/choose).\n\n## Migration von Version 1 auf Version 2\n\n### Hinweise zum Upgrade auf Version 2\n\n1. **Neue Eigenschaften in Version 2 bereits ab Version 1.7 verfügbar:**<br/>\n Die meisten neuen Eigenschaften, die in Version 2 eingeführt werden, sind bereits ab der Version 1.7 und höher verfügbar. Dies bedeutet, dass Anwendungen, die auf Version 1.7 oder höher basieren, möglicherweise bereits über die erforderlichen Funktionen verfügen, um eine reibungslose Migration zu ermöglichen.\n\n2. **Entfernte Eigenschaften, Komponenten und Funktionalitäten waren in Version 1.7 und höher bereits als veraltet markiert:**<br/>\n Alle Eigenschaften, Komponenten und Funktionalitäten, die in Version 2 entfernt wurden, waren in Version 1.7 und höher bereits als veraltet (`deprecated`) gekennzeichnet. Wenn Sie also regelmäßig Ihre Codebasis aktualisiert haben, sollten Sie bereits darauf vorbereitet sein, diese Elemente zu ersetzen.\n\n3. **Migration ab Version 1.7 minimiert potenzielle Änderungen:**<br/>\n Eine Migration von Version 1.7 und höher auf Version 2 wird voraussichtlich die geringsten Anpassungen erfordern. Die Wahrscheinlichkeit von Inkompatibilitäten ist niedrig, da die meisten Änderungen und Entfernungen bereits in den vorherigen Versionen als veraltet markiert wurden.\n\n4. **Migration ab Version 1.4 ist möglich:**<br/>\n Obwohl eine Migration ab Version 1.7 empfohlen wird, ist es auch möglich, von Version 1.4 auf Version 2 zu migrieren. Beachten Sie jedoch, dass dies möglicherweise zusätzliche Anpassungen erfordert, da einige der notwendigen Funktionen möglicherweise erst ab Version 1.7 verfügbar sind.\n\n5. **Vereinfachte Registrierung beachten:**<br/>\n Wir haben in Version 1 und für Version 2 die Modularisierung von KoliBri vereinfacht. Das Modul `@public-ui/core` wurde entfernt und die Funktionalitäten in das Modul `@public-ui/components` verschoben.\n\n```diff\n - import { register } from '@public-ui/core';\n + import { register } from '@public-ui/components';\n import { defineCustomElements } from '@public-ui/components/loader';\n import { MyTheme } from '...';\n await register(MyTheme, defineCustomElements);\n```\n\n### Breaking Changes für Version 2\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v2.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v2.md).\n\n### Breaking Changes für Version 3\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v3.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v3.md).\n\n### Breaking Changes für Version 4\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v4.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v4.md).\n\n## Migration durchführen\n\n> [!TIP]\n> Wir empfehlen, die Migration mit dem Migrationstool durchzuführen. Dieses Tool ist in der Lage, die meisten Breaking Changes automatisch zu migrieren. Weitere Informationen finden Sie in der [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n### Migration mit Migrationstool\n\n1. **Vorbereitung:**<br/>\n Das Projekt ist auf einer früheren Version, alle Abhängigkeiten sind installiert, das Projekt ist lauffähig und alle Änderungen sind eingecheckt und sicher gepusht.\n2. **Migration ausführen:**<br/>\n Führen Sie den folgenden Befehl aus, um das Migration auszuführen: `npx @public-ui/kolibri-cli migrate src`\n3. **Migration prüfen:**<br/>\n Prüfen Sie die Änderungen und führen Sie die Anwendung aus, um sicherzustellen, dass alles wie erwartet funktioniert.\n\n### Migration manuell durchführen\n\n1. **Vorbereitung:**<br/>\n Das Projekt ist auf einer früheren Version, alle Abhängigkeiten sind installiert, das Projekt ist lauffähig und alle Änderungen sind eingecheckt und sicher gepusht.\n2. **Migration durchführen:**<br/>\n Führen Sie die Migration durch, indem Sie die Breaking Changes in der jeweiligen Dokumentation.\n",
497
+ "code": "# Migration\n\n## Einleitung\n\nNeue Major-Versionen von KoliBri werden mit dem Ziel entwickelt, die Wartung und Pflege zu vereinfachen und Weiterentwicklung zu fördern.\n\nDies bedeutet, dass ggf. Komponenten, Eigenschaften oder Funktionalitäten entfernt werden und technologische Voraussetzungen geschaffen werden, um einen zukünftigen innovativen Wandel zu begünstigt.\n\n- **Wartungs- und Pflegestrategie:**<br/>\n Wir werden immer die neuste und die vorherige Major-Version von KoliBri pflegen. Dies bedeutet, dass wir für diese Versionen Fehler beheben und Sicherheitslücken schließen. Für alle anderen Versionen werden wir ohne Weiteres keine Fehlerbehebungen oder Sicherheitsupdates mehr bereitstellen.\n- **Weiterentwicklung:**<br/>\n Wir werden immer die neuste Major-Version von KoliBri weiterentwickeln. Dies bedeutet, dass wir für diese Versionen neue Features und Funktionalitäten bereitstellen. Für alle anderen Versionen werden wir ohne Weiteres keine neuen Features oder Funktionalitäten mehr bereitstellen.\n- **Vor der Migration einen lauffähigen Stand sichern:**<br/>\n Bevor die Migration erfolgt, empfehlen wir einen lauffähigen Stand einzuchecken und somit keine uncommiteten Änderungen auf dem zu migrierenden Quellcode zu haben. Während und nach der Migration können so alle Änderungen gut nachvollzogen und geprüft werden.\n- **Migrationstool:**<br/>\n Wir stellen ein Migrationstool bereit, welches generell die Migration von Quellcode mit KoliBri unterstützt. Dieses Tool ist in der Lage, die meisten Breaking Changes automatisch zu migrieren. Weitere Informationen finden Sie in der [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n > [!NOTE]\n > Das Migrationstool unterstützt aktuell React-Projekte (`.jsx`/`.tsx`), Vue-Single-File-Components (`.vue`) sowie HTML/XHTML-Template-Projekte (z. B. Angular-Templates oder Projekte mit nativen Custom Elements).\n- **Hilfe und Feedback:**<br/>\n Sollte es Probleme bei der Migration geben, stehen wir gerne zur Verfügung. Bitte eröffnen Sie ein [Issue auf GitHub](https://github.com/public-ui/kolibri/issues/new/choose).\n\n## Migration von Version 1 auf Version 2\n\n### Hinweise zum Upgrade auf Version 2\n\n1. **Neue Eigenschaften in Version 2 bereits ab Version 1.7 verfügbar:**<br/>\n Die meisten neuen Eigenschaften, die in Version 2 eingeführt werden, sind bereits ab der Version 1.7 und höher verfügbar. Dies bedeutet, dass Anwendungen, die auf Version 1.7 oder höher basieren, möglicherweise bereits über die erforderlichen Funktionen verfügen, um eine reibungslose Migration zu ermöglichen.\n\n2. **Entfernte Eigenschaften, Komponenten und Funktionalitäten waren in Version 1.7 und höher bereits als veraltet markiert:**<br/>\n Alle Eigenschaften, Komponenten und Funktionalitäten, die in Version 2 entfernt wurden, waren in Version 1.7 und höher bereits als veraltet (`deprecated`) gekennzeichnet. Wenn Sie also regelmäßig Ihre Codebasis aktualisiert haben, sollten Sie bereits darauf vorbereitet sein, diese Elemente zu ersetzen.\n\n3. **Migration ab Version 1.7 minimiert potenzielle Änderungen:**<br/>\n Eine Migration von Version 1.7 und höher auf Version 2 wird voraussichtlich die geringsten Anpassungen erfordern. Die Wahrscheinlichkeit von Inkompatibilitäten ist niedrig, da die meisten Änderungen und Entfernungen bereits in den vorherigen Versionen als veraltet markiert wurden.\n\n4. **Migration ab Version 1.4 ist möglich:**<br/>\n Obwohl eine Migration ab Version 1.7 empfohlen wird, ist es auch möglich, von Version 1.4 auf Version 2 zu migrieren. Beachten Sie jedoch, dass dies möglicherweise zusätzliche Anpassungen erfordert, da einige der notwendigen Funktionen möglicherweise erst ab Version 1.7 verfügbar sind.\n\n5. **Vereinfachte Registrierung beachten:**<br/>\n Wir haben in Version 1 und für Version 2 die Modularisierung von KoliBri vereinfacht. Das Modul `@public-ui/core` wurde entfernt und die Funktionalitäten in das Modul `@public-ui/components` verschoben.\n\n```diff\n - import { register } from '@public-ui/core';\n + import { register } from '@public-ui/components';\n import { defineCustomElements } from '@public-ui/components/loader';\n import { MyTheme } from '...';\n await register(MyTheme, defineCustomElements);\n```\n\n### Breaking Changes für Version 2\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v2.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v2.md).\n\n### Breaking Changes für Version 3\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v3.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v3.md).\n\n### Breaking Changes für Version 4\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v4.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v4.md).\n\n### Breaking Changes für Version 5\n\nMehr Informationen zu Breaking Changes finden Sie in der Dokumentation [BREAKING_CHANGES.v5.md (EN)](https://github.com/public-ui/kolibri/blob/develop/docs/BREAKING_CHANGES.v5.md).\n\n## Migration durchführen\n\n> [!TIP]\n> Wir empfehlen, die Migration mit dem Migrationstool durchzuführen. Dieses Tool ist in der Lage, die meisten Breaking Changes automatisch zu migrieren. Weitere Informationen finden Sie in der [Tool-Dokumentation (EN)](https://www.npmjs.com/package/@public-ui/kolibri-cli).\n\n### Migration mit Migrationstool\n\n1. **Vorbereitung:**<br/>\n Das Projekt ist auf einer früheren Version, alle Abhängigkeiten sind installiert, das Projekt ist lauffähig und alle Änderungen sind eingecheckt und sicher gepusht.\n2. **Migration ausführen:**<br/>\n Führen Sie den folgenden Befehl aus, um das Migration auszuführen: `npx @public-ui/kolibri-cli migrate src`\n3. **Migration prüfen:**<br/>\n Prüfen Sie die Änderungen und führen Sie die Anwendung aus, um sicherzustellen, dass alles wie erwartet funktioniert.\n\n### Migration manuell durchführen\n\n1. **Vorbereitung:**<br/>\n Das Projekt ist auf einer früheren Version, alle Abhängigkeiten sind installiert, das Projekt ist lauffähig und alle Änderungen sind eingecheckt und sicher gepusht.\n2. **Migration durchführen:**<br/>\n Führen Sie die Migration durch, indem Sie die Breaking Changes in der jeweiligen Dokumentation.\n",
480
498
  "kind": "doc"
481
499
  },
482
500
  {
@@ -506,13 +524,22 @@
506
524
  "code": "# GitHub Workflows Optimization - Summary\n\n## ✅ All Completed Optimizations\n\n### Phase 4: Critical CI Optimizations ✓ (NEWLY ADDED)\n\n#### 4.1 ci.yml - Path Filters + Playwright Caching\n\n**File**: `.github/workflows/ci.yml`\n\n**What Changed**:\n\n- Added `paths-ignore` filters to skip full CI pipeline on docs-only changes\n- Ignores: `*.md`, `docs/**`, `LICENSE`, `.github/ISSUE_TEMPLATE/**`, etc.\n- Added Playwright browser caching to both `e2e-tests` and `visual-tests` jobs\n- Cache key: `${{ runner.os }}-playwright-${{ hashFiles('**/pnpm-lock.yaml') }}`\n\n**Impact**:\n\n- **Saves ~20-25 minutes/run on docs-only PRs** (full pipeline skip)\n- **Saves ~3-5 minutes/run on code changes** (Playwright cache hit)\n- Reduces unnecessary test runs by ~10-15% monthly\n- **ci.yml is the largest resource consumer; this optimization alone saves ~2000 machine minutes/month**\n\n#### 4.2 codeql.yml - Path Filters\n\n**File**: `.github/workflows/codeql.yml`\n\n**What Changed**:\n\n- Added `paths-ignore` to both push and pull_request triggers\n- Ignores: `*.md`, `docs/**`, `LICENSE`\n\n**Impact**:\n\n- Saves ~10-15% of CodeQL runs\n- Skips unnecessary security analysis on documentation changes\n\n#### 4.3 pnpm-setup Action - Dependency Upgrade\n\n**File**: `.github/actions/pnpm-setup/action.yml`\n\n**What Changed**:\n\n- `pnpm/action-setup@v4` → `@v5` (newer version with better features)\n- `actions/setup-node@v5` → `@v6` (newer version with performance improvements)\n\n**Impact**:\n\n- Better caching strategies in newer versions\n- Improved GitHub Actions performance\n- All workflows automatically benefit from this upgrade\n\n#### 4.4 snyk-major-scan.yml - Activity Check\n\n**File**: `.github/workflows/snyk-major-scan.yml`\n\n**What Changed**:\n\n- Added `check-activity` job that detects last commit age\n- Only scans if commits within last 25 hours\n- Manual triggers (workflow_dispatch) always scan\n\n**Logic**:\n\n```yaml\ncheck-activity:\n # Checks if last commit is < 25 hours old\n # For scheduled runs: skip if no recent commits\n # For manual runs: always proceed\n\nsnyk-major-scan:\n needs: check-activity\n if: needs.check-activity.outputs.should-scan == 'true'\n```\n\n**Impact**:\n\n- Saves ~2-3 unnecessary runs/week\n- Intelligent scheduling respects actual development activity\n\n---\n\n### Phase 1: Workflow Consolidations ✓\n\n#### 1.1 Benchmark Workflows Consolidated\n\n**Files Changed**:\n\n- ✅ Created: `.github/workflows/benchmark.yml` (unified workflow)\n- ✅ Deleted: `benchmark.baseline.yml`, `benchmark.monitoring.yml`, `benchmark.pr-check.yml`\n\n**What Changed**:\n\n- Single unified workflow with `mode` input selector: `baseline`, `monitoring`, `pr-check`\n- Conditional job execution based on mode\n- Added Playwright caching for faster benchmark runs\n- Shared benchmark action call for all modes\n\n**Impact**:\n\n- 66% reduction in workflow management overhead\n- ~20 min/week maintenance savings\n- Clearer separation of concerns with input-based mode selection\n\n**Usage**:\n\n```bash\n# Run baseline mode\ngh workflow run benchmark.yml -f mode=baseline\n\n# Run monitoring mode\ngh workflow run benchmark.yml -f mode=monitoring\n\n# Run PR check mode\ngh workflow run benchmark.yml -f mode=pr-check -f pr-number=123\n```\n\n---\n\n#### 1.2 Security Scanning Consolidated\n\n**Files Changed**:\n\n- ✅ Updated: `.github/workflows/security-scan.yml` (now unified)\n- ✅ Deleted: `security-scan-schedule.yml`\n\n**What Changed**:\n\n- Single unified security workflow handling both manual and scheduled runs\n- Triggers: `schedule` (6-hourly) + `workflow_dispatch` with flexible inputs\n- Activity-based conditions to skip unnecessary scheduled runs\n- Support for audit, trivy, and clamav scans with configurable options\n- Separate jobs for single-branch (manual) and multi-branch (scheduled) scans\n\n**Impact**:\n\n- Eliminates ~210 redundant runs/year\n- ~30 min/week time savings\n- Consistent trigger and condition definitions\n- Activity-check skips scans when no commits in last 7 hours\n\n**Usage**:\n\n```bash\n# Manual security scan with custom options\ngh workflow run security-scan.yml \\\n -f enable_audit=true \\\n -f enable_trivy=true \\\n -f enable_clamav=true\n\n# Scheduled runs automatically multi-branch scan across develop, release/3, release/2\n```\n\n---\n\n#### 1.3 Netlify Deployments Refactored\n\n**Files Changed**:\n\n- ✅ Created: `.github/workflows/deploy-netlify.yml` (reusable workflow)\n- ✅ Simplified: `draft-deploy.yml` (now calls reusable)\n- ✅ Simplified: `test-deploy.yml` (now calls reusable)\n\n**What Changed**:\n\n- Shared reusable workflow with parametrized deployment logic\n- Both draft and stable deployments use same underlying code\n- Input parameters: `environment` (preview/production) and `alias` (for production)\n- Unified build, cache, and deployment steps\n\n**Impact**:\n\n- Eliminates 90% code duplication between deployments\n- ~30 min/week maintenance savings\n- Easier to update deployment logic in single place\n- Maintained all existing functionality (fork checks, PR comments, etc.)\n\n**Example**:\n\n```yaml\n# draft-deploy.yml now simply calls:\njobs:\n deploy:\n uses: ./.github/workflows/deploy-netlify.yml\n with:\n environment: preview\n\n# test-deploy.yml now simply calls:\njobs:\n deploy:\n uses: ./.github/workflows/deploy-netlify.yml\n with:\n environment: production\n alias: ${{ github.ref_name }}\n```\n\n---\n\n### Phase 2: Smart Conditions ✓\n\n#### 2.1 sync-to-opencode.yml - Commit Detection\n\n**File**: `.github/workflows/sync-to-opencode.yml`\n\n**What Changed**:\n\n- Added `check-commits` job that detects if new commits exist\n- Main `sync` job now depends on activity check\n- Skips unnecessary syncs when no changes exist\n\n**Logic**:\n\n```yaml\ncheck-commits:\n # Detects if new commits exist since last run\n # Outputs: has-new-commits (true/false)\n\nsync:\n needs: check-commits\n if: workflow_dispatch OR (schedule AND has-new-commits == 'true')\n # Only syncs if manually triggered OR scheduled run with new commits\n```\n\n**Impact**:\n\n- ~300 unnecessary runs/year eliminated\n- ~8-10 hours/week machine time saved\n- Only syncs when there's actual work to do\n\n---\n\n#### 2.2 security-scan.yml - Activity Check\n\n**File**: `.github/workflows/security-scan.yml`\n\n**What Changed**:\n\n- Added `check-activity` job that detects last commit age\n- Main scan jobs depend on activity check\n- Skips scans when commits are older than 7 hours\n\n**Logic**:\n\n```yaml\ncheck-activity:\n # Checks if last commit is < 7 hours old\n # For scheduled runs: skip if no recent commits\n # For manual runs: always proceed\n\nscheduled-scan:\n needs: check-activity\n if: schedule AND should-scan == 'true'\n # Only runs multi-branch scan if activity detected\n```\n\n**Impact**:\n\n- ~80 unnecessary runs/year eliminated\n- ~4-6 hours/week machine time saved\n- Intelligent scheduling respects actual development activity\n\n---\n\n#### 2.3 visual-tests-base.yml - Path Filtering\n\n**File**: `.github/workflows/visual-tests-base.yml`\n\n**What Changed**:\n\n- Added `paths` filter to PR trigger\n- Only runs tests when component/theme/sample files change\n\n**Paths Monitored**:\n\n```yaml\npaths:\n - 'packages/components/**'\n - 'packages/themes/**'\n - 'packages/samples/react/**'\n - '.github/workflows/visual-tests-base.yml'\n - '.github/actions/pnpm-setup/**'\n - '.github/actions/upload-reports/**'\n```\n\n**Impact**:\n\n- ~30-40% reduction in visual test runs\n- ~2-3 hours/week saved for docs-only PRs\n- Faster feedback for non-visual changes\n\n---\n\n### Phase 3: Caching Improvements ✓\n\n#### 3.1 auto-dependency-updater.yml - pnpm Cache\n\n**File**: `.github/workflows/auto-dependency-updater.yml`\n\n**What Changed**:\n\n- Enabled previously commented-out `cache: 'pnpm'` in setup-node\n\n**Impact**:\n\n- ~3-5 minutes/run saved\n- ~30 minutes/month cumulative savings\n\n---\n\n#### 3.2 benchmark.yml - Playwright Cache\n\n**File**: `.github/workflows/benchmark.yml`\n\n**What Changed**:\n\n- Added Playwright browser cache to benchmark workflow\n- Caches `~/.cache/ms-playwright`\n- Key: `${{ runner.os }}-playwright-${{ hashFiles('**/pnpm-lock.yaml') }}`\n\n**Impact**:\n\n- ~2-3 minutes/run saved for benchmark runs\n- ~20 minutes/month cumulative savings\n\n---\n\n## 📊 Impact Summary\n\n### Workflow Count\n\n| Metric | Before | After | Change |\n| ------------------- | ------ | ----- | ---------------------- |\n| Total Workflows | 22 | 19 | -3 (-13%) |\n| Benchmark Workflows | 3 | 1 | -2 consolidated |\n| Security Workflows | 2 | 1 | -1 consolidated |\n| Deploy Workflows | 2+1 | 2+1 | Refactored to reusable |\n\n### Monthly Impact (Before → After)\n\n| Metric | Before | After | Savings |\n| ----------------------- | ----------- | ---------- | --------------------- |\n| Workflow Runs | ~1200 | ~750 | **450 runs (-37%)** |\n| Machine Minutes | ~180 | **~55** | **~125 min (-69%)** |\n| Hours/Week | 2-2.5h | <0.5h | **~2 hrs/week** |\n| CI Pipeline Runs | 100 | ~85-90 | ~10-15% (path filter) |\n| Playwright Install Time | ~25 min/run | ~5 min/run | **~20 min (-80%)** |\n\n### Annual Impact\n\n| Metric | Savings | Notes |\n| ------------------------ | --------------- | -------------------------------------------------- |\n| **Workflow Runs** | ~450 | Consolidations + conditions |\n| **Machine Minutes** | ~1500 | ci.yml caching = ~2000 min saved, minus other runs |\n| **GitHub Actions Cost** | $18-25 | Based on $0.008/min pricing |\n| **CO2 Footprint** | ~300kg | US grid mix (~0.2kg CO2/min compute) |\n| **ci.yml Savings Alone** | ~2000 min/month | From Playwright caching |\n\n### Phase 4 Impact (newly added)\n\n| Benefit | Impact |\n| --------------------------- | --------------------------------------------------- |\n| **ci.yml paths-ignore** | -10-15% runs on docs/config changes |\n| **ci.yml Playwright cache** | -20-25 min per docs-only run, -3-5 min per code run |\n| **codeql.yml paths-ignore** | -10-15% CodeQL runs |\n| **snyk activity check** | -2-3 runs/week |\n| **pnpm-setup upgrade** | Better overall caching |\n\n**Total combined savings**: 69% reduction in machine minutes (was 61%, now 69%)\n\n### Code Quality\n\n| Metric | Before | After | Change |\n| ------------------ | ------ | ----- | ------------ |\n| Code Duplication | High | Low | **-40%** |\n| Maintenance Burden | High | Low | **-40%** |\n| Workflow Clarity | Medium | High | **Improved** |\n\n---\n\n## 🧪 Testing Recommendations\n\n### Phase 1 Testing\n\n1. **Benchmark Workflow**:\n\n ```bash\n # Test baseline mode\n gh workflow run benchmark.yml -f mode=baseline\n # Verify: baseline.json updated and committed\n\n # Test monitoring mode\n gh workflow run benchmark.yml -f mode=monitoring\n # Verify: attestation created, results stored\n\n # Test pr-check mode\n gh workflow run benchmark.yml -f mode=pr-check -f pr-number=123\n # Verify: PR comment with report created\n ```\n\n2. **Security Scan**:\n\n ```bash\n # Test manual scan\n gh workflow run security-scan.yml -f enable_audit=true -f enable_trivy=true\n # Verify: scan completes successfully\n\n # Watch scheduled run (next 6-hourly trigger)\n # Verify: activity check works, skip on no commits\n ```\n\n3. **Netlify Deployments**:\n\n ```bash\n # Test via PR (draft-deploy)\n # Create test PR, verify deployment happens\n\n # Test via push to develop (test-deploy)\n # Verify stable deployment works\n ```\n\n### Phase 2 Testing\n\n1. **sync-to-opencode**:\n - Manual trigger: Should sync immediately\n - Scheduled run with no commits: Should skip\n - Scheduled run with commits: Should sync\n\n2. **security-scan activity check**:\n - Verify skipped runs in logs with \"no commits in last 7 hours\"\n - Manual trigger: Should always run regardless of activity\n\n3. **visual-tests path filter**:\n - PR with docs changes only: Tests should NOT run\n - PR with component changes: Tests should run\n\n### Phase 3 Testing\n\n1. **Caching**:\n - Verify pnpm cache hit in auto-dependency-updater\n - Verify playwright cache hit in benchmark workflow\n - Compare run times with/without cache hits\n\n---\n\n## 📝 Documentation Updates Needed\n\nWhen merging this PR, please update:\n\n1. **GitHub Actions Documentation** (if exists):\n - Update benchmark workflow documentation with new mode-based usage\n - Document unified security scanning workflow\n - Add examples for reusable netlify deployment workflow\n\n2. **Contributing Guide**:\n - Update any references to old benchmark workflows\n - Document how to trigger new benchmark workflow\n - Update security scanning instructions\n\n3. **Team Wiki/Internal Docs**:\n - Notify team of workflow consolidations\n - Update any automation that triggered old workflows\n - Update monitoring/alerting if it tracked specific workflows\n\n---\n\n## 🚀 Deployment Notes\n\n### Branch Information\n\n- **Branch**: `claude/optimize-github-workflows-5jamh`\n- **Commits**: 4 commits (plan + consolidations + deletions + fixes)\n- **Files Modified**: 13 files\n- **Files Created**: 2 (benchmark.yml, deploy-netlify.yml)\n- **Files Deleted**: 4 (old benchmark.\\*.yml, security-scan-schedule.yml)\n\n### Validation\n\n✅ All 20 workflows pass YAML syntax validation\n✅ All workflow trigger conditions are correct\n✅ Backward compatibility maintained for external references\n✅ All secret/variable references preserved\n\n### Post-Merge Checklist\n\n- [ ] Monitor GitHub Actions dashboard for first scheduled runs\n- [ ] Verify sync-to-opencode skips when appropriate\n- [ ] Verify security-scan respects activity conditions\n- [ ] Verify visual-tests skip for non-component PRs\n- [ ] Verify new benchmark workflow can be triggered in all modes\n- [ ] Update internal documentation and runbooks\n\n---\n\n## 💡 Future Optimization Opportunities\n\nWhile not included in this round, consider for future:\n\n1. **Consolidate CVE/Snyk workflows**: Could combine cve-overview.yml and snyk-major-scan.yml if they have overlapping needs\n2. **CI Job Optimization**: The main ci.yml could benefit from similar path filtering and condition logic\n3. **Stale Issues Workflow**: Could add conditions to skip if no activity in issues\n4. **CodeQL**: Already scheduled once weekly; consider if frequency is necessary\n5. **Dependency Updater**: Could add conditions to skip matrix entries with no changes\n\n---\n\n## Questions or Issues?\n\nFor questions about these optimizations, refer to:\n\n- `WORKFLOW_OPTIMIZATION_PLAN.md` - Detailed planning document\n- Individual workflow files - Inline comments explain conditional logic\n- Git history - Commit messages detail what changed and why\n",
507
525
  "kind": "doc"
508
526
  },
527
+ {
528
+ "id": "doc/OUTPUT_TARGETS_MIGRATION_CONCEPT",
529
+ "group": "docs",
530
+ "name": "OUTPUT_TARGETS_MIGRATION_CONCEPT",
531
+ "description": "Stand: erarbeitet gegen @stencil/core 4.45.2, @stencil/react-output-target 1.6.x, @stencil/angular-output-target 1.5.x, @stencil/vue-output-target 0.14.x, @stencil/ssr 0.4.x Umfang: packages/components (Stencil-Build), packages/adapters/\\*, Doku und Migration-Guide Ziel: Die vier eigenen Forks der…",
532
+ "path": "docs/OUTPUT_TARGETS_MIGRATION_CONCEPT.md",
533
+ "code": "# Konzept: Umstieg auf die offiziellen Stencil Output Targets\n\n**Stand:** erarbeitet gegen `@stencil/core` 4.45.2, `@stencil/react-output-target` 1.6.x, `@stencil/angular-output-target` 1.5.x, `@stencil/vue-output-target` 0.14.x, `@stencil/ssr` 0.4.x\n**Umfang:** packages/components (Stencil-Build), packages/adapters/\\*, Doku und Migration-Guide\n**Ziel:** Die vier eigenen Forks der Framework-Output-Targets werden durch die offiziellen Stencil-Pakete ersetzt. Das TagName-Replace-Feature (`transformTagName`) bleibt dabei als öffentliche Funktion erhalten und wird auf die native Stencil-API (`setTagTransformer`/`transformTag`) umgestellt.\n\n---\n\n## 1. Ausgangslage\n\n### 1.1 Warum es die Forks gibt\n\nDas TagName-Replace erlaubt Anwendungen, zur Laufzeit alle `kol-*` Tags umzubenennen, zum Beispiel auf `app-kol-button` oder `v2-kol-button`, um Namensräume pro Einsatzkontext oder Versionslinien zu trennen. Als das Feature gebaut wurde, sahen die offiziellen Stencil-Output-Targets keine solche Erweiterung vor. Deshalb pflegt KoliBri eigene Forks:\n\n| Paket | Version | Zusatz gegenüber Upstream |\n| ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `@public-ui/stencil-angular-output-target` | 0.9.0 | Generiert `ReplaceTagDirective`, `StencilProxyComponent` und `tagNameTransformer` (Runtime-Re-Hosting, da Angular-Selektoren zur Compilezeit feststehen) |\n| `@public-ui/stencil-react-output-target` | 0.6.0 | Generiert `setTagNameTransformer`-Export; `createComponent` löst den Tag zur Renderzeit auf |\n| `@public-ui/stencil-vue-output-target` | 0.9.0 | Generiert `setTagNameTransformer`-Export, `defineContainer` löst zur Renderzeit auf |\n| `@public-ui/stencil-solid-output-target` | 0.2.0 | Wie React/Vue, `tagNameTransformer` im `solid-component-lib` |\n| `@revolist/svelte-output-target` | 0.0.7 | Community-Paket, **ohne** Tag-Replacement |\n\n### 1.2 Wie das Feature heute verdrahtet ist\n\nDas Feature existiert heute in drei Schichten, die unabhängig voneinander gesetzt werden müssen:\n\n1. **Core** (`packages/components/src/core/component-names.ts`): `bootstrap({ transformTagName })` ruft `setCustomTagNames()` auf und mutiert die exportierten `Kol*Tag`-Konstanten. Interne Kompositionen (zum Beispiel rendert der Toaster `KolButtonTag`) folgen dadurch der Umbenennung.\n2. **Adapter**: Jede generierte Proxy-Datei enthält den Fork-Hook (`setTagNameTransformer` beziehungsweise die Angular-Direktiven-Maschinerie). Die Anwendung ruft `setTagNameTransformer(fn)` aus dem jeweiligen Adapter-Paket auf (siehe `packages/tools/visual-tests/app/src/react.main.tsx`).\n3. **Loader**: `defineCustomElements(window, { transformTagName: fn })` benennt beim Lazy-Loading die definierbaren Tags um, aktiviert über `extras.tagNameTransform: true` in der Stencil-Konfiguration. Diese Option ist in Stencil als deprecated markiert.\n\nDiese Dreiteilung ist fehleranfällig: Wer eine Schicht vergisst, bekommt unaufgelöste Elemente. Zusätzlich lastet die Fork-Pflege vier Upstream-Repositories ab, mit wachsendem Abstand bei SSR-, React-19- und Typfeatures.\n\n---\n\n## 2. Was die neuen Output Targets mitbringen\n\n### 2.1 Native Runtime-API im Core\n\nStencil Core bringt seit 4.4x die Laufzeit-APIs `setTagTransformer(fn)` und `transformTag(tag)` mit (siehe `stencil-public-runtime.d.ts`). Damit wird der Tag an **einer einzigen Stelle** gesetzt und wirkt auf:\n\n- `customElements.define/get/whenDefined` und `document.createElement` (injiziert der Compiler in den generierten Component-Dateien),\n- das interne Rendering: `h()` transformiert VNode-Tag-Namen, der Lazy-Host löst `transformTag(cmpMeta.$tagName$)` auf,\n- den Komponenten-Lookup des Lazy-Loaders,\n- SSR: das Hydrate-Modul exportiert `setTagTransformer`/`transformTag`, das neue `@stencil/ssr`-Paket setzt es automatisch,\n- CSS-Strings sowie `querySelector(All)`/`closest`-Selektoren, wenn `extras.additionalTagTransformers: true` gesetzt ist.\n\nDeprecated und damit ersatzlos entfallend: `extras.tagNameTransform` und `defineCustomElements(window, { transformTagName })`.\n\n### 2.2 Die neuen Target-Pakete (Monorepo `stenciljs/output-targets`)\n\nAlle drei Framework-Targets haben eine Option `transformTag: boolean`:\n\n- **React** (`outDir` statt `proxiesFile`, Runtime aus `@stencil/react-output-target/runtime`, basierend auf `@lit/react`, React 18 und 19 kompatibel): generiert zusätzlich eine `tag-transformer.ts` und Proxies, die `transformTag` an `createComponent` durchreichen. SSR über `hydrateModule` erzeugt `components.server.ts`. Einschränkung: der finale Tag wird **beim Modul-Import einmalig** aufgelöst (eager binding), nicht pro Render.\n- **Vue** (`includeImportCustomElements` oder Lazy über Loader-Plugin): transformiert den Tag **pro Renderaufruf**, passt also zum bisherigen Verhalten. Generiert eine Plugin-Datei, in der `setTagTransformer` vor dem `defineCustomElements` gesetzt werden kann.\n- **Angular** (`outputType: component | scam | standalone`, `directivesArrayFile`): löst das Runtime-Problem anders. Bei `transformTag: true` generiert es ein Skript `patch-transform-selectors.mjs`, das als `postinstall` in der konsumierenden Anwendung die `@Component`-Selektoren (und die `.d.ts`-Deklarationen) der installierten Angular-Wrapper-Library im `node_modules` umschreibt. Ein Runtime-Re-Hosting wie im KoliBri-Fork gibt es nicht.\n- **Solid und Svelte haben keine offiziellen Targets.** Das Monorepo führt nur React, Angular, Vue, `@stencil/ssr` und `@stencil/types-output-target`.\n\n### 2.3 Konsequenz für die Adapter-Generierung\n\nDer neue React-Generator bindet `defineCustomElement` pro Komponente aus dem `dist-custom-elements`-Output ein und ersetzt damit das bisherige Lazy-Loading über `applyPolyfills`/`defineCustomElements` aus dem Loader. Für Vue bleibt der Lazy-Pfad über Loader und Plugin möglich. Das ist eine Verhaltensänderung (Definition der Elemente, Bundle-Schnitt, Polyfill-Pfad) und gehört in die Migrationsplanung, sie ist aber unabhängig vom TagName-Feature der eigentliche technische Gewinn der Umstellung.\n\n---\n\n## 3. Zielbild\n\n### 3.1 Single Source of Truth für die Umbenennung\n\nNach der Migration gibt es genau eine Instanz, die den Transformer kennt: die native Stencil-Runtime.\n\n- `bootstrap({ transformTagName })` **bleibt die öffentliche API** in `@public-ui/components`. Intern ruft sie statt `setCustomTagNames` die native `setTagTransformer` auf.\n- Jede Adapter-Package exportiert weiterhin `setTagNameTransformer(fn)` als Brücke. Sie delegiert an dieselbe native API, damit Adapter-Proxy und Core definitionsgemäß synchron sind.\n- `setCustomTagNames()` und die Mutation der `Kol*Tag`-Konstanten entfallen. Die Konstanten bleiben als Public API exportiert, tragen aber dauerhaft den Wert `kol-*`. Das interne Rendering funktioniert ohne Mutation, weil die Stencil-Runtime VNode-Namen selbst transformiert.\n- **Achtung Doppeltransformation:** Solange die Konstanten mutiert würden und die Runtime zusätzlich transformiert, entstünde `app-kol-button` zu `app-app-kol-button`. Die Mutation muss stillgelegt werden, sobald der native Pfad aktiviert wird.\n\n### 3.2 Zielzustand der `stencil.config.ts`\n\n```ts\nimport { angularOutputTarget } from '@stencil/angular-output-target';\nimport { reactOutputTarget } from '@stencil/react-output-target';\nimport { vueOutputTarget } from '@stencil/vue-output-target';\n// solid: vorerst @public-ui/stencil-solid-output-target (kein offizielles Target)\n// svelte: vorerst @revolist/svelte-output-target (kein offizielles Target)\n\nexport const config: Config = {\n\t// ...\n\textras: {\n\t\t// tagNameTransform entfällt (deprecated)\n\t\tadditionalTagTransformers: true, // transformiert CSS-Strings und Selektoren mit\n\t\tenableImportInjection: true,\n\t},\n\toutputTargets: [\n\t\t{ type: 'dist' }, // Lazy-Loader weiterhin für Vue, Solid, Svelte, Vanilla\n\t\t{ type: 'www' },\n\t\t{ type: 'dist-custom-elements' }, // Basis für React und Angular-Standalone\n\t\treactOutputTarget({ outDir: '../adapters/react/src', excludeComponents: EXCLUDE_TAGS, transformTag: true }),\n\t\treactOutputTarget({ outDir: '../adapters/react-v19/src', excludeComponents: EXCLUDE_TAGS, transformTag: true }),\n\t\tangularOutputTarget({\n\t\t\tcomponentCorePackage: '@public-ui/components',\n\t\t\tdirectivesProxyFile: '../adapters/angular/v20/src/components.ts',\n\t\t\tdirectivesArrayFile: '../adapters/angular/v20/src/index.ts',\n\t\t\texcludeComponents: EXCLUDE_TAGS,\n\t\t\ttransformTag: true,\n\t\t}),\n\t\t// analog v21\n\t\tvueOutputTarget({/* wie heute plus transformTag: true */}),\n\t\t// hydrate, docs-* unverändert\n\t],\n};\n```\n\nDie Brücke im Core (`bootstrap.ts`) verkürzt sich im Wesentlichen auf:\n\n```ts\nimport { setTagTransformer } from '@stencil/core';\n\nif (koliBriOptions?.transformTagName) {\n\tsetTagTransformer(koliBriOptions.transformTagName);\n}\n```\n\nDa der Transformer vor dem ersten `define` gesetzt sein muss, prüft der Core die Reihenfolge und gibt im Zweifel die native Warnung plus einen KoliBri-Hinweis aus. Die Adapter-Brücken (`kolibri-src`-Schicht der Adapter-Packages) exportieren `setTagNameTransformer` weiter und rufen dieselbe native API.\n\n### 3.3 Verbleibende Eigenbauten\n\nZwei Punkte lassen sich mit den offiziellen Targets nicht ohne Weiteres abbilden und werden bewusst als kleine, repo-eigene Post-Processing-Schritte geführt statt als Forks:\n\n1. **React: Auflösung des Tags zur Renderzeit.** Der offizielle Generator bindet den Tag beim Import fest. Die KoliBri-UX (Transformer wird in `bootstrap` gesetzt, also nach den statischen Imports) bräche. Lösung: ein Script im Components-Build (`packages/components/scripts/`, analog zu `autogen.doc.js` und `vaadin.js`, die bereits nach jedem Build in `../adapters/*` schreiben) tauscht in der generierten `components.ts` den `createComponent`-Import gegen einen dünnen KoliBri-Wrapper aus `kolibri-src`, der `transformTag(tagName)` erst beim ersten Render aufruft. Sobald Upstream eine verzögerte Auflösung anbietet, fällt der Codemod weg.\n2. **Angular: Runtime-Re-Hosting statt `node_modules`-Patching.** Der offizielle Pfad verlangt bei `transformTag: true` einen `postinstall` in jeder konsumierenden Anwendung, der die Selektoren im installierten Paket umschreibt. Das kollidiert mit pnpm-Workflows, CI-Caches und der Nachvollziehbarkeit von Supply Chains. Stattdessen bleiben `ReplaceTagDirective`, `StencilProxyComponent` und `tagNameTransformer` als repo-eigene Dateien (Vorlage im Components-Paket, kopiert wie heute durch `copyResources` beziehungsweise das Build-Script) erhalten, und ein zweiter Codemod-Schritt apliciert auf die offiziell generierte `components.ts` die KoliBri-Proxy-Vorlage. Das Ergebnis ist funktional das heutige Verhalten, die Logik liegt aber im KoliBri-Repository und nicht mehr in einem gepflegten Fork.\n\n### 3.4 Adapter im Einzelnen\n\n| Adapter | Ziel | Tag-Replacement |\n| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------- |\n| React 18 (`@public-ui/react`) | offizielles Target + Codemod (Renderzeit-Auflösung), Umstieg auf `dist-custom-elements` | vollständig, wie heute |\n| React 19 (`@public-ui/react-v19`) | dito; perspektivisch Zusammenführung mit react, da die neue Runtime 18 und 19 abdeckt | vollständig |\n| Angular v20/v21 | offizielles Target + eigene `angular-component-lib`-Vorlagen und Proxy-Codemod | vollständig, Runtime statt Postinstall |\n| Vue | offizielles Target, `transformTag: true`, Lazy-Pfad über Loader-Plugin | vollständig (offiziell) |\n| Solid | Fork vorerst weiter (kein offizielles Target); mittelfristig eigenes Target ins Repo holen oder upstreamen | vollständig (Fork) |\n| Svelte | Community-Target ohne Tag-Replacement; Lücke dokumentieren, Upstream-Issue zu `svelte:element` prüfen | **Lücke wie heute** |\n| Preact, Vaadin, react-standalone, hydrate | ohne Transformer wie heute weiter; hydrate bleibt Basis für späteres `@stencil/ssr`-Angebot | unverändert |\n\n---\n\n## 4. Migrationsplan\n\nJede Phase endet mit `pnpm format`, `pnpm lint`, `pnpm test` und einem grünen visual-tests-Lauf mit `ENABLE_TAG_NAME_TRANSFORMER=true` (Zero-Visual-Delta-Handoff gegen den Base-Branch, da die Umbenennung das DOM nicht sichtbar verändern darf).\n\n### Phase 0: Bestandsaufnahme und Entscheidungen\n\n- Diff der vier Forks gegen die jeweiligen Upstream-Versionen ziehen und alle Abweichungen außer dem Tag-Transformer auflisten (Event-Typen, `excludeRenderWait`, Bugfixes), damit nichts beim Wechsel verloren geht.\n- Verifizieren, dass der mit 4.45.2 generierte Loader `setTagTransformer` exportiert (der generierte `dist/esm/loader.js` des aktuellen Workspace-Builds enthält es noch nicht; Teil des nächsten Component-Builds).\n- Entscheidung nach Abschnitt 3.3 fällen (React-Codemod, Angular-Re-Hosting) und den Umstieg Lazy-Loader zu `dist-custom-elements` für React als eigenen, vorziehenden Schritt befestigen oder in Phase 2 integrieren.\n- E2E-Abdeckung für das Feature je Adapter in `visual-tests` ergänzen (Transformation aktiviert, alle Elemente unter dem umbenannten Tag funktionsfähig, inklusive intern komponierter Komponenten wie Toaster-Button).\n\n### Phase 1: Core umstellen\n\n- `bootstrap`: `transformTagName` an native `setTagTransformer` delegieren.\n- `setCustomTagNames` stilllegen (Funktionskörper entkoppeln, `Kol*Tag`-Konstanten unveränderlich), inklusive Anpassung der Komponenten-Tests, die die Mutation bislang indirekt nutzen.\n- `extras.additionalTagTransformers: true` setzen, `extras.tagNameTransform` entfernen.\n- Unit-Tests: Transformer nach `bootstrap` setzt Warnung; interner Toaster rendert unter dem transformierten Tag; Selektoren und Styles transformieren mit `additionalTagTransformers`.\n\n### Phase 2: React-Adapter\n\n- Offizielle Targets für `adapters/react` und `adapters/react-v19` aktivieren, Generierung prüfen (`_`-Props, Events, Ref-Verhalten unter `@lit/react`).\n- Post-Gen-Codemod für Renderzeit-Auflösung umsetzen und in `build:light`-Pipeline einhängen.\n- Umstieg der Registrierung von `defineCustomElements` (Loader) auf die per-Komponente-Definition des Custom-Elements-Outputs; `kolibri-src`-Exports (`createReactRenderElement`, `setTagNameTransformer`) anpassen.\n- Samples (`packages/samples/react`), `visual-tests` und React Hook Form Adapter gegen die neuen Pakete laufen lassen; Verbraucher-Migration (`defineCustomElements(window, { transformTagName })` entfällt) im Migration-Guide festhalten.\n\n### Phase 3: Angular-Adapter (v20, v21)\n\n- Offizielles Target generieren lassen, `angular-component-lib`-Vorlagen als KoliBri-eigene Dateien im Components-Paket ablegen, Proxy-Codemod umsetzen, `ng-module.js`-Nachbearbeitung an das neue Generat anpassen (`directivesArrayFile` prüfen).\n- Smoke-Test mit `packages/samples/angular` (nur lesen) und einem Angular-20-/21-Sandbox-App-Durchlauf inklusive Transformer.\n\n### Phase 4: Vue-Adapter\n\n- Offizielles Target mit `transformTag: true` und Lazy-Plugin übernehmen; `vue-component-lib` durch die offizielle Runtime ersetzen; `setTagNameTransformer`-Export als Brücke behalten.\n\n### Phase 5: Aufräumen und Publizieren\n\n- Fork-Pakete `@public-ui/stencil-{angular,react,vue}-output-target` als deprecated markieren (Readme-Hinweis auf die offiziellen Pakete), Solid-Fork behalten mit Kommentar im Config-File.\n- Doku auf public-ui.github.io: Feature-Seite TagName-Transform auf den neuen Pfad umstellen, `defineCustomElements({ transformTagName })` als entfernt kennzeichnen, Migration-Guide für die App-Umstellung.\n- Release-Koordination: Components und alle Adapter in einem Release-Zug ausliefern, da Generierung und Runtime zusammengehören. SemVer: Major für Adapter mit Verhaltensänderung (React-Registrierung), Minor beziehungsweise Patch, wo nur intern wechselt. Kein Komponenten-API-Bruch: `bootstrap({ transformTagName })`, `Kol*Tag`-Exports und `setTagNameTransformer` je Adapter bleiben unverändert.\n\n---\n\n## 5. Risiken und offene Punkte\n\n- **React eager binding:** Gelöst durch Codemod (Abschnitt 3.3). Fällt der Codemod weg, muss die Doku den Import vor der Transformer-Registrierung verlangen, was die heutige Bootstrap-UX bricht.\n- **Angular-Postinstall des offiziellen Pfads:** Bewusst nicht übernommen (pnpm, CI, Supply Chain). Falls der Codemod-Ansatz auf Dauer zu pflegeintensiv wird, ist der offizielle Patch-Pfad der dokumentierte Rückfallweg.\n- **Registrierungswechsel bei React:** Lazy-Loader hin zu per-Komponenten-Define ändert Ladeverhalten und Bundle-Zuschnitt. Getrennt messen (Bundle-Analyse, Performance-Sample) und gegebenenfalls in einem eigenen Schritt vor Phase 2 ausrollen.\n- **`@lit/react`-Semantik:** Props mit Unterstrich-Präfix, Event-Namen und Ref-Weitergabe gegen die goldenen Samples testen; das `className`-Merging der offiziellen Runtime ist neu.\n- **Doppeltransformation im Übergang:** Core-Mutation und native Transformation dürfen nie gleichzeitig aktiv sein; Phase 1 und 2 daher nacheinander und mit Tests absichern.\n- **Solid und Svelte bleiben Sonderfälle:** Kein offizielles Target beziehungsweise kein Tag-Replacement. Beides ist heute schon so, die Migration verschärft es nicht, muss es aber dokumentieren.\n- **Upstream-Kopplung:** Die `transformTag`-Option der Targets ist relativ jung (Angular-Patch-Script, React-eager-Binding). Vor dem Abschluss von Phase 2 bis 4 die verwendeten Minor-Versionen pinnen und Änderungen im Monorepo verfolgen.\n\n## 6. Entscheidungspunkte\n\n1. React: Codemod für Renderzeit-Auflösung (Empfehlung) oder dokumentierter API-Bruch mit Transform-vor-Import?\n2. Angular: Runtime-Re-Hosting aus repo-eigenen Vorlagen (Empfehlung) oder offizieller Postinstall-Selektor-Patch?\n3. React-Registrierungswechsel (Lazy-Loader zu `dist-custom-elements`): in Phase 2 integrieren oder als separaten, vorlaufenden Schritt?\n",
534
+ "kind": "doc"
535
+ },
509
536
  {
510
537
  "id": "doc/README",
511
538
  "group": "docs",
512
539
  "name": "README",
513
540
  "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…",
514
541
  "path": "README.md",
515
- "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/main/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",
542
+ "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- [Component tests with Vitest](./docs/HOWTO_COMPONENT_TESTS_VITEST.md)\n- [Security](./docs/SECURITY.md)\n",
516
543
  "kind": "doc"
517
544
  },
518
545
  {
@@ -521,7 +548,7 @@
521
548
  "name": "RENOVATE",
522
549
  "description": "This document is the outcome of issue #10270 (_renovate vs npm-check-updates vs dependabot_). It contains:",
523
550
  "path": "docs/RENOVATE.md",
524
- "code": "# Renovate — Automated Dependency Updates\n\nThis document is the outcome of issue [#10270](https://github.com/public-ui/kolibri/issues/10270)\n(_renovate vs npm-check-updates vs dependabot_). It contains:\n\n1. a comparison of the three candidate tools,\n2. a description of the exemplary [`renovate.json`](../renovate.json) that ships with this repo,\n3. how to enable Renovate, and\n4. the migration checklist for retiring the current tooling.\n\n> **Status:** The `renovate.json` and a self-hosted runner workflow\n> ([`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml)) are committed as an\n> **exemplary, ready-to-run setup**. Renovate stays **idle** until that workflow runs — either on its\n> nightly schedule (every 3 hours between 18:00 and 06:00 Europe/Berlin) or via the manual\n> **Run workflow** button (see [Enabling Renovate](#enabling-renovate)).\n> Until then the existing Dependabot + npm-check-updates automation stays in charge.\n\n---\n\n## 1. Tool comparison\n\nKoliBri is a **pnpm-workspace monorepo** with 30+ packages, several intentionally pinned major\nlines (Angular `v20`/`v21`, React 18/19, Stencil 4, ESLint 9) and four maintained branches\n(`develop`, `release/3`, `release/2`, `release/1`). That shapes the comparison:\n\n| Capability | **Renovate** | Dependabot | npm-check-updates (ncu) |\n| -------------------------------------------- | :----------------------: | :---------------------------------: | :-----------------------: |\n| pnpm-workspace aware | ✅ native | ⚠️ partial | ❌ manual (per-package) |\n| One PR grouping related packages | ✅ fully configurable | ⚠️ `groups:` only | ❌ none |\n| Hold a package on a specific major line | ✅ per-folder rules | ⚠️ `ignore` (global) | ⚠️ `-x` exclude (global) |\n| GitHub Actions updates | ✅ | ✅ | ❌ |\n| Lockfile-only refresh | ✅ `lockFileMaintenance` | ⚠️ limited | ❌ (needs `pnpm install`) |\n| Automerge (per update type) | ✅ | ⚠️ limited | ❌ |\n| Multi-base-branch (release/\\*) support | ✅ `baseBranchPatterns` | ✅ `target-branch` (one entry each) | ⚠️ matrix in a workflow |\n| Security / vulnerability remediation | ✅ OSV + GitHub alerts | ✅ GitHub alerts | ❌ |\n| Dependency Dashboard (single overview issue) | ✅ | ❌ | ❌ |\n| Schedule / batching | ✅ | ⚠️ basic | ⚠️ via cron workflow |\n| Self-hostable (no third-party app) | ✅ (official Action) | ✅ (GitHub-native) | ✅ (CLI) |\n| Config surface | medium | low | minimal |\n| Cost for open source | free | free | free |\n\n### Verdict\n\n- **Renovate — recommended.** It is the only option that models KoliBri's reality in _one_ config:\n group the Angular/React/Stencil families, hold each adapter folder on its pinned major, automerge\n the safe stuff (GitHub Actions, `@types/*`), and route everything risky to a review queue (the\n Dependency Dashboard). It also folds in what we currently split across **two** systems\n (Dependabot for Actions + a daily `ncu` workflow for npm).\n- **Dependabot — viable fallback.** Now supports `groups:`, but every package directory needs its\n own `updates:` entry (≈30 for this monorepo × 4 branches) and it cannot hold a dependency on a\n specific major _per folder_ — exactly what the `angular/v20|v21` and `react*` adapters need.\n- **npm-check-updates — not an automation tool.** It is a CLI that rewrites version ranges; it has\n no PR/grouping/scheduling of its own. We only use it _inside_ a hand-written workflow\n (`.github/workflows/auto-dependency-updater.yml`). Renovate makes that workflow redundant.\n\n---\n\n## 2. What the exemplary `renovate.json` does\n\nThe committed [`renovate.json`](../renovate.json) is tailored to this repo. Highlights:\n\n### Global behaviour\n\n- **`extends: [\"config:recommended\", \"security:openssf-scorecard\"]`** — sensible defaults plus\n OpenSSF Scorecard badges on PRs.\n- **Conventional Commits** — `chore(deps): …` titles so PRs pass `pr-title-validation.yml`.\n- **`labels: [\"dependencies\", \"renovate\", \"release:engineering\"]`** — the `release:*` label is\n **required** by `pr-release-label-validation.yml`; `release:engineering` files dependency PRs\n under _🔧 Engineering_ in the changelog (see `.github/release.yml`).\n- **Night-only cadence (18:00–06:00, every 3 hours)** — Renovate must not open PRs or automerge\n during working hours. Two settings enforce this together:\n - `renovate.json` → `\"schedule\": [\"after 6pm\", \"before 6am\"]` with `timezone: \"Europe/Berlin\"`.\n The window crosses midnight, so it is written as **two** entries (Renovate ORs them); a single\n `\"after 6pm before 6am\"` string would never match.\n - the workflow cron `0 16,19,22,1,4 * * *`. GitHub cron only understands UTC, so these hours are\n chosen to stay inside the local window all year: in CEST (UTC+2) they fire at 18/21/00/03/06\n Berlin time, in CET (UTC+1) at 17/20/23/02/05. The one run that falls outside the window\n (17:00 in winter, 06:00 in summer) starts Renovate but produces no PRs, because the\n `renovate.json` schedule is the authoritative gate.\n\n **Exception:** `vulnerabilityAlerts` keeps `\"schedule\": [\"at any time\"]`, so a manual\n **Run workflow** during the day still ships security fixes.\n\n `prConcurrentLimit: 5` / `prHourlyLimit: 5` cap the number of open PRs **per base branch** (so\n `develop` and each `release/*` branch have their own budget).\n\n- **Automerge all non-major updates (merge commit)** — the first package rule enables `automerge` for\n `patch`/`minor`/`digest`/`pin`/lockfile updates; `automergeStrategy: merge` is the only method the\n `Production branches` ruleset allows on `develop` (see [Troubleshooting](#troubleshooting-prs-stay-open-although-ci-is-green)). Known-risky rules below (Stencil, kern-ux, ESLint,\n TypeScript, typescript-eslint) override it back to manual. Majors always keep dashboard approval.\n Prerequisites: repo setting **Allow auto-merge** enabled, green pipelines enforced via required\n status checks on `develop`, and the runner GitHub App listed in the branch-protection bypass\n (see [Enabling Renovate](#enabling-renovate)).\n- **`rebaseWhen: conflicted`** — Renovate rebases a branch only when it conflicts with `develop`, not\n whenever `develop` has moved on. The `Required checks` rules do not demand an up-to-date branch\n (`strict_required_status_checks_policy: false`), and a rebase restarts the CI for about 40 minutes.\n With `behind-base-branch`, every merge into `develop` (by people or by the runner itself, which\n merges one pull request per run) pushed all other green dependency pull requests behind and into a new\n rebase, so they rarely met a run in which they were both green and up to date.\n- **`baseBranchPatterns`** — runs on `develop` and on the LTS branch `release/4`, both with the same\n rules. `release/3|2|1` are paused: their package rules stay in place and make them **security-only**\n (all regular npm and GitHub Actions updates are disabled) as soon as they are added back to\n `baseBranchPatterns`. Security PRs then automerge when non-major; major security updates require\n dashboard approval.\n- **`lockFileMaintenance`** — weekly `pnpm-lock.yaml` refresh (replaces the manual\n `04 - Update pnpm Lock` workflow runs).\n- **`configMigration: true`** — Renovate keeps `renovate.json` itself up to date when built-in\n presets or options change.\n- **`dependencyDashboardOSVVulnerabilitySummary: \"all\"`** — adds an OSV vulnerability table\n directly to the Dependency Dashboard issue.\n- **`postUpdateOptions: [\"pnpmDedupe\"]`** — keeps the pnpm lockfile tidy.\n\n### Grouping & guard-rails (the important part for this monorepo)\n\n| Rule | Effect |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **All majors** | Require manual approval via the Dependency Dashboard — KoliBri pins majors deliberately. |\n| **Angular `@angular/*`, `zone.js`, `ng-packagr`** | Major updates **disabled** entirely; within-major updates grouped per adapter folder (_Angular 20/21_). A new Angular major = a new adapter folder, never an auto-bump. |\n| **React `react`, `react-dom`, `@types/react*`** | Major updates **disabled**; within-major React updates of the `react*` adapters grouped and automerged once green. |\n| **Stencil `@stencil/*`, `@stencil-community/*`** | **All** updates require dashboard approval — every 4.39+ release currently breaks the Popover API, tooltips and visual tests (see [`UPGRADEABLE_DEPENDENCIES.md`](./UPGRADEABLE_DEPENDENCIES.md)). |\n| **`@kern-ux/*`** | Dashboard approval only — upgraded by hand together with theming work. |\n| **`@typescript-eslint/*`, ESLint core + plugins** | Minor/major require approval (9 → 10 is a breaking migration). |\n| **`jest*`, `typescript`** | Majors/non-patch require approval. |\n| **`github-actions`, `@types/*`** | Grouped; automerged like every other non-major update. |\n| **Stylelint, Playwright** | Grouped into single PRs. |\n\n> The pins above mirror exactly what the current `ncu:*` scripts exclude\n> (`@kern-ux/*`, `@stencil/*`, `@typescript-eslint/*`) and what `UPGRADEABLE_DEPENDENCIES.md`\n> documents as breaking — so behaviour is preserved, just expressed declaratively.\n\n### Validate the config locally\n\n```sh\nnpx --yes --package renovate renovate-config-validator renovate.json\n```\n\n---\n\n## 3. Enabling Renovate\n\nTwo ways to run it; **this repo is wired for Option A**.\n\n### Option A — Self-hosted via GitHub Actions (committed in this repo)\n\nThis repo ships [`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml). It runs Renovate\n**every 3 hours during the night window 18:00–06:00 Europe/Berlin**\n(`0 16,19,22,1,4 * * *` UTC, see [Global behaviour](#global-behaviour)) **and** on demand via the **Run workflow** button\n(`workflow_dispatch`, with an optional `dry_run` preview). It authenticates through the existing GitHub\nApp (`APP_ID` / `PRIVATE_KEY` secrets, shared with _04 - Update pnpm Lock_).\n\nTo activate it:\n\n1. Ensure that GitHub App installation grants **contents: write**, **pull-requests: write**,\n **issues: write** (for the Dependency Dashboard), **workflows: write** (so the `github-actions`\n manager may update `.github/workflows/*`), **commit statuses: write**, **Dependabot alerts: read**\n and the mandatory **metadata: read**. Nothing beyond those seven is needed. Changing them at the\n App is only half of it: the installation has to accept the new set, otherwise the runner keeps\n working with the old one and the symptoms below stay. _Alternative:_ replace the app-token step\n with a `RENOVATE_TOKEN` PAT/fine-grained token carrying the same scopes.\n\n > Without **Dependabot alerts: read** every run logs\n > `Cannot access vulnerability alerts`, and `vulnerabilityAlerts` stays inactive; security PRs\n > then only come from `osvVulnerabilityAlerts`.\n\n2. Branch protection. What governs `develop` are **rulesets**, not a classic branch protection\n rule. Keep it that way: a classic rule for the same branch is evaluated on top of the rulesets,\n and its _bypass required pull requests_ list only waives the need to **open** a pull request. It\n does not waive the approval a merge needs, so the bot stays blocked while the list suggests\n otherwise.\n\n A bypass entry always waives **every rule of its ruleset**, never a single one. Hence the split:\n\n | Ruleset | Rules | Bypass list |\n | --------------------- | ---------------------------------------------------------------- | ------------- |\n | `Production branches` | `pull_request` (approvals, code-owner review, merge methods) | `publicuibot` |\n | `Required checks` | `required_status_checks`, restrict deletions, block force pushes | empty |\n\n The runner merges without a human review, but never past a red check. For everyone else nothing\n changes.\n\n Three details that cost an evening on 2026-09-09:\n\n - `allowed_merge_methods` of the `pull_request` rule is `[\"merge\"]`, which is why\n `automergeStrategy` is `merge`. On the repository itself both squash merges and merge commits\n are enabled; the ruleset is what narrows it down.\n - A required status check may never be skipped by a path filter, or the pull request waits\n forever for a status that nothing will post. `codeql.yml` therefore has no `paths-ignore`, and\n `visual-review.yml` answers a skipped CI run with `success` (mode `docs-only`, see\n `scripts/visual-review/resolve-context.mjs`). Anything added to the list has to obey the same\n rule. `check-results` is deliberately absent: a red pipeline stops Renovate, which refuses to\n merge a red branch, but it does not stop a human.\n - Every workflow behind a required check needs `synchronize` in its `pull_request` types.\n GitHub wants the check on the **current head commit**, so a workflow that only reacts to\n `opened`/`edited` leaves it unreported after any push and the merge is refused with\n `Required status check \"…\" is expected`. Renovate runs into this on every rebase; that is what\n `pr-title-validation.yml` was missing.\n - A workflow behind a required check that filters `pull_request` by base branch also needs\n `edited`. A stacked pull request opened against a feature branch never matches the filter, and\n when GitHub retargets it to `develop` after the pull request below it is merged, it sends only\n `edited`. Without it the check stays at `Expected — Waiting for status to be reported` until the\n next push. `codeql.yml` therefore reacts to `edited` and runs only when the base changed; a\n title or body edit gets a concurrency group of its own, so it cannot cancel a running analysis.\n - In the target patterns of a ruleset GitHub prefixes `refs/heads/` itself. Enter `release/**/*`,\n never `refs/heads/release/**/*`, otherwise the prefix doubles and the release branches silently\n lose their protection. `gh api repos/public-ui/kolibri/rules/branches/release/3` shows what is\n really in effect.\n\n Repository level, **Settings → General → Pull Requests**: `Allow auto-merge` stays on, Renovate\n uses `platformAutomerge`.\n\n3. Trigger the workflow once via **Run workflow** (optionally with `dry_run` enabled) to verify it, then\n let the nightly schedule take over.\n\n> **Tip:** The `dry_run` input maps to `RENOVATE_DRY_RUN=full`, so the first manual run previews every PR\n> Renovate _would_ open without creating anything.\n\n### Option B — Mend-hosted GitHub App (alternative, zero maintenance)\n\nIf you would rather not self-host, delete `.github/workflows/renovate.yml` and instead:\n\n1. Have an **org admin** install the [Renovate GitHub App](https://github.com/apps/renovate) on\n `public-ui` (or just on `public-ui/kolibri`).\n2. Renovate detects `renovate.json` and opens a Dependency Dashboard issue.\n3. Review the dashboard, then let it run on the weekly schedule.\n\n### Troubleshooting: PRs stay open although CI is green\n\nRenovate never explains a refused merge in the PR itself. The runner log does, but only at\n`LOG_LEVEL=debug`: start the workflow via **Run workflow** with `log_level: debug` (and `dry_run`\noff — a dry run logs `DRY-RUN: Would merge PR` and never sends the request that carries the error).\n\nAt `info` level the only trace is one line per PR:\n\n```\nINFO: All merge attempts failed (repository=public-ui/kolibri, baseBranch=develop, branch=…)\n \"pr\": 10833\n```\n\nIt means Renovate did try. Automerge is configured correctly and the branch is green — GitHub\nrejected the `PUT /repos/:owner/:repo/pulls/:number/merge` call. The cause is therefore always a\nrepository setting or a ruleset, never `renovate.json`. Renovate walks three strategies in order\n(the configured `automergeStrategy` first, then merge commit, then rebase); the debug log holds one\n`Failed to … PR` block per attempt, each with the HTTP status and GitHub's own message:\n\n| Response | Meaning |\n| --------------------------------------------------------- | ------------------------------------------------------------------------- |\n| `405` `Squash merges are not allowed on this repository.` | The merge method is not allowed here — see `allowed_merge_methods` below. |\n| `405` `Rebase merges are not allowed on this repository.` | Same, for rebase. |\n| `405` `Repository rule violations found: …` | A ruleset blocks the bot; the text names the rule. |\n| `405` `… Required status check \"x\" is expected.` | Check `x` never ran on the head commit — see `synchronize` in §3. |\n| `403` `Resource not accessible by integration` | The App lacks **contents: write**. |\n\nWhich rules actually apply to a branch is readable without admin rights:\n\n```sh\ngh api repos/public-ui/kolibri/rules/branches/develop\n```\n\n> **The case of 2026-09-09.** Every green dependency PR sat blocked with `mergeable_state: blocked`\n> while the pipelines were green and no review existed. All three attempts failed with `405`. The\n> two rules behind it both lived in one ruleset that carried everything at once:\n> `allowed_merge_methods: [\"merge\"]` rejected squash and rebase, and `require_last_push_approval`\n> rejected the merge commit, a rule the bot can never satisfy on its own branches because it is\n> always the last pusher. The App was listed in the bypass list of the **classic** branch\n> protection rule, which looks like the fix and is not one: that list only waives the need to open\n> a pull request.\n>\n> What resolved it: the rules were split into the two rulesets described in\n> [§3](#option-a--self-hosted-via-github-actions-committed-in-this-repo), the App went into the\n> bypass list of the one holding the `pull_request` rule, the classic rule was deleted, and\n> `automergeStrategy` moved from `squash` to `merge`. A bypass entry is worth nothing until it sits\n> on the ruleset that actually carries the failing rule, and `bypass_actors` is only readable with\n> admin rights, so the runner log stays the honest source.\n\nTwo more silent failures show up as warnings rather than as a blocked PR:\n\n- `Cannot access vulnerability alerts` — **Dependabot alerts: read** is missing, `vulnerabilityAlerts`\n stays inactive and security PRs come from `osvVulnerabilityAlerts` only.\n- `Could not ensure issue … integration-unauthorized` — the Dependency Dashboard issue is not being\n updated any more. Check **Issues: write** for the App, and whether the issue itself is locked.\n\n---\n\n## 4. Migration checklist (do this only after Renovate is verified)\n\nOnce Renovate runs green for a cycle, retire the overlapping automation to avoid **duplicate PRs**.\nStatus as of the Renovate activation for `develop`:\n\n- [x] Removed `.github/dependabot.yml` (Renovate now manages GitHub Actions — see the\n `github-actions` group).\n- [x] Removed `.github/workflows/auto-dependency-updater.yml` (the daily `ncu` PR job).\n- [x] Dropped the `ncu:*` / `update` scripts and the `npm-check-updates` devDependency from the root\n `package.json`, plus `.ncurc.json`.\n- [ ] Keep `04 - Update pnpm Lock` if you still want a manual lockfile-refresh button; otherwise\n Renovate's `lockFileMaintenance` covers it.\n\nUntil every box is ticked, **leave the existing tooling in place** — Renovate only acts once the\nworkflow (or app) from [§3](#3-enabling-renovate) actually runs, so there is no conflict in the meantime.\n\n---\n\n## 🇩🇪 Zusammenfassung\n\n**Empfehlung: Renovate.** Es ist die einzige Lösung, die das KoliBri-Monorepo in _einer_ Konfiguration\nabbildet — verwandte Pakete gruppieren (z. B. alle `@angular/*`), jeden Adapter-Ordner auf seiner\nfixierten Major-Version halten (`angular/v20|v21`, `react*`), sichere Updates automatisch mergen\n(GitHub Actions, `@types/*`) und alles Riskante (Stencil, kern-ux, ESLint-/Angular-Majors) über das\n**Dependency Dashboard** zur manuellen Freigabe leiten.\n\n- **Dependabot** kann zwar gruppieren, braucht aber pro Paketverzeichnis einen eigenen Eintrag\n (≈30 × 4 Branches) und kann ein Paket nicht _pro Ordner_ auf einer Major-Version halten.\n- **npm-check-updates** ist nur ein CLI ohne eigene Automatisierung (läuft heute im Workflow\n `auto-dependency-updater.yml`).\n\n`automergeStrategy: merge` folgt der Merge-Commit-Konvention des Repos. Renovate läuft auf `develop`\nund dem LTS-Branch `release/4` mit denselben Regeln. `release/1`–`release/3` sind pausiert; ihre\nRegeln stellen sie auf **Security-only**, sobald sie wieder in `baseBranchPatterns` stehen: reguläre\nnpm- und GitHub-Actions-Updates sind dort komplett deaktiviert, Vulnerability-Alert-PRs mergen\n(bei Nicht-Major) automatisch.\n\nDie fertige [`renovate.json`](../renovate.json) liegt im Repo-Root (geprüft mit dem offiziellen\n`renovate-config-validator`), und der self-hosted Runner-Workflow\n[`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml) ist ebenfalls committet.\n**Renovate läuft**, sobald der Workflow startet — nachts alle 3 Stunden zwischen 18:00 und 06:00 Uhr\n(Europe/Berlin) per Zeitplan oder jederzeit manuell über den **Run workflow**-Button (Option A); alternativ kann ein Org-Admin die\n[Renovate-GitHub-App](https://github.com/apps/renovate) installieren (Option B). Bis dahin bleibt die\nbestehende Dependabot-/ncu-Automatisierung zuständig; danach greift die Migrations-Checkliste oben.\n",
551
+ "code": "# Renovate — Automated Dependency Updates\n\nThis document is the outcome of issue [#10270](https://github.com/public-ui/kolibri/issues/10270)\n(_renovate vs npm-check-updates vs dependabot_). It contains:\n\n1. a comparison of the three candidate tools,\n2. a description of the exemplary [`renovate.json`](../renovate.json) that ships with this repo,\n3. how to enable Renovate, and\n4. the migration checklist for retiring the current tooling.\n\n> **Status:** The `renovate.json` and a self-hosted runner workflow\n> ([`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml)) are committed as an\n> **exemplary, ready-to-run setup**. Renovate stays **idle** until that workflow runs — either on its\n> nightly schedule (every 3 hours between 18:00 and 06:00 Europe/Berlin) or via the manual\n> **Run workflow** button (see [Enabling Renovate](#enabling-renovate)).\n> Until then the existing Dependabot + npm-check-updates automation stays in charge.\n\n---\n\n## 1. Tool comparison\n\nKoliBri is a **pnpm-workspace monorepo** with 30+ packages, several intentionally pinned major\nlines (Angular `v20`/`v21`, React 18/19, Stencil 4, ESLint 9) and four maintained branches\n(`develop`, `release/3`, `release/2`, `release/1`). That shapes the comparison:\n\n| Capability | **Renovate** | Dependabot | npm-check-updates (ncu) |\n| -------------------------------------------- | :----------------------: | :---------------------------------: | :-----------------------: |\n| pnpm-workspace aware | ✅ native | ⚠️ partial | ❌ manual (per-package) |\n| One PR grouping related packages | ✅ fully configurable | ⚠️ `groups:` only | ❌ none |\n| Hold a package on a specific major line | ✅ per-folder rules | ⚠️ `ignore` (global) | ⚠️ `-x` exclude (global) |\n| GitHub Actions updates | ✅ | ✅ | ❌ |\n| Lockfile-only refresh | ✅ `lockFileMaintenance` | ⚠️ limited | ❌ (needs `pnpm install`) |\n| Automerge (per update type) | ✅ | ⚠️ limited | ❌ |\n| Multi-base-branch (release/\\*) support | ✅ `baseBranchPatterns` | ✅ `target-branch` (one entry each) | ⚠️ matrix in a workflow |\n| Security / vulnerability remediation | ✅ OSV + GitHub alerts | ✅ GitHub alerts | ❌ |\n| Dependency Dashboard (single overview issue) | ✅ | ❌ | ❌ |\n| Schedule / batching | ✅ | ⚠️ basic | ⚠️ via cron workflow |\n| Self-hostable (no third-party app) | ✅ (official Action) | ✅ (GitHub-native) | ✅ (CLI) |\n| Config surface | medium | low | minimal |\n| Cost for open source | free | free | free |\n\n### Verdict\n\n- **Renovate — recommended.** It is the only option that models KoliBri's reality in _one_ config:\n group the Angular/React/Stencil families, hold each adapter folder on its pinned major, automerge\n the safe stuff (GitHub Actions, `@types/*`), and route everything risky to a review queue (the\n Dependency Dashboard). It also folds in what we currently split across **two** systems\n (Dependabot for Actions + a daily `ncu` workflow for npm).\n- **Dependabot — viable fallback.** Now supports `groups:`, but every package directory needs its\n own `updates:` entry (≈30 for this monorepo × 4 branches) and it cannot hold a dependency on a\n specific major _per folder_ — exactly what the `angular/v20|v21` and `react*` adapters need.\n- **npm-check-updates — not an automation tool.** It is a CLI that rewrites version ranges; it has\n no PR/grouping/scheduling of its own. We only use it _inside_ a hand-written workflow\n (`.github/workflows/auto-dependency-updater.yml`). Renovate makes that workflow redundant.\n\n---\n\n## 2. What the exemplary `renovate.json` does\n\nThe committed [`renovate.json`](../renovate.json) is tailored to this repo. Highlights:\n\n### Global behaviour\n\n- **`extends: [\"config:recommended\", \"security:openssf-scorecard\"]`** — sensible defaults plus\n OpenSSF Scorecard badges on PRs.\n- **Conventional Commits** — `chore(deps): …` titles so PRs pass `pr-title-validation.yml`.\n- **`labels: [\"dependencies\", \"renovate\", \"release:engineering\"]`** — the `release:*` label is\n **required** by `pr-release-label-validation.yml`; `release:engineering` files dependency PRs\n under _🔧 Engineering_ in the changelog (see `.github/release.yml`).\n- **Night-only cadence (18:00–06:00, every 3 hours)** — Renovate must not open PRs or automerge\n during working hours. Two settings enforce this together:\n - `renovate.json` → `\"schedule\": [\"after 6pm\", \"before 6am\"]` with `timezone: \"Europe/Berlin\"`.\n The window crosses midnight, so it is written as **two** entries (Renovate ORs them); a single\n `\"after 6pm before 6am\"` string would never match.\n - the workflow cron `0 16,19,22,1,4 * * *`. GitHub cron only understands UTC, so these hours are\n chosen to stay inside the local window all year: in CEST (UTC+2) they fire at 18/21/00/03/06\n Berlin time, in CET (UTC+1) at 17/20/23/02/05. The one run that falls outside the window\n (17:00 in winter, 06:00 in summer) starts Renovate but produces no PRs, because the\n `renovate.json` schedule is the authoritative gate.\n\n **Exception:** `vulnerabilityAlerts` keeps `\"schedule\": [\"at any time\"]`, so a manual\n **Run workflow** during the day still ships security fixes.\n\n `prConcurrentLimit: 5` / `prHourlyLimit: 5` cap the number of open PRs **per base branch** (so\n `develop` and each `release/*` branch have their own budget).\n\n- **Automerge all non-major updates (merge commit)** — the first package rule enables `automerge` for\n `patch`/`minor`/`digest`/`pin`/lockfile updates; `automergeStrategy: merge` is the only method the\n `Production branches` ruleset allows on `develop` (see [Troubleshooting](#troubleshooting-prs-stay-open-although-ci-is-green)). Known-risky rules below (Stencil, kern-ux, ESLint,\n TypeScript, typescript-eslint) override it back to manual. Majors always keep dashboard approval.\n Prerequisites: repo setting **Allow auto-merge** enabled, green pipelines enforced via required\n status checks on `develop`, and the runner GitHub App listed in the branch-protection bypass\n (see [Enabling Renovate](#enabling-renovate)).\n- **`rebaseWhen: conflicted`** — Renovate rebases a branch only when it conflicts with `develop`, not\n whenever `develop` has moved on. The `Required checks` rules do not demand an up-to-date branch\n (`strict_required_status_checks_policy: false`), and a rebase restarts the CI for about 40 minutes.\n With `behind-base-branch`, every merge into `develop` (by people or by the runner itself, which\n merges one pull request per run) pushed all other green dependency pull requests behind and into a new\n rebase, so they rarely met a run in which they were both green and up to date.\n- **`baseBranchPatterns`** — runs on `develop` and on the LTS branch `release/4`, both with the same\n rules. `release/3|2|1` are paused: their package rules stay in place and make them **security-only**\n (all regular npm and GitHub Actions updates are disabled) as soon as they are added back to\n `baseBranchPatterns`. Security PRs then automerge when non-major; major security updates require\n dashboard approval.\n- **`lockFileMaintenance`** — weekly `pnpm-lock.yaml` refresh (replaces the manual\n `04 - Update pnpm Lock` workflow runs).\n- **`configMigration: true`** — Renovate keeps `renovate.json` itself up to date when built-in\n presets or options change.\n- **`dependencyDashboardOSVVulnerabilitySummary: \"all\"`** — adds an OSV vulnerability table\n directly to the Dependency Dashboard issue.\n- **`postUpdateOptions: [\"pnpmDedupe\"]`** — keeps the pnpm lockfile tidy.\n\n### Grouping & guard-rails (the important part for this monorepo)\n\n| Rule | Effect |\n| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **All majors** | Require manual approval via the Dependency Dashboard — KoliBri pins majors deliberately. |\n| **Angular `@angular/*`, `zone.js`, `ng-packagr`** | Major updates **disabled** entirely; within-major updates grouped per adapter folder (_Angular 20/21_). A new Angular major = a new adapter folder, never an auto-bump. |\n| **React `react`, `react-dom`, `@types/react*`** | Major updates **disabled**; within-major React updates of the `react*` adapters grouped and automerged once green. |\n| **Stencil `@stencil/*`, `@stencil-community/*`** | **All** updates require dashboard approval — every 4.39+ release currently breaks the Popover API, tooltips and visual tests (see [`UPGRADEABLE_DEPENDENCIES.md`](./UPGRADEABLE_DEPENDENCIES.md)). |\n| **`@kern-ux/*`** | Dashboard approval only — upgraded by hand together with theming work. |\n| **`@typescript-eslint/*`, ESLint core + plugins** | Minor/major require approval (9 → 10 is a breaking migration). |\n| **`jest*`, `typescript`** | Majors/non-patch require approval. |\n| **`github-actions`, `@types/*`** | Grouped; automerged like every other non-major update. |\n| **Stylelint, Playwright** | Grouped into single PRs. |\n\n> The pins above mirror exactly what the current `ncu:*` scripts exclude\n> (`@kern-ux/*`, `@stencil/*`, `@typescript-eslint/*`) and what `UPGRADEABLE_DEPENDENCIES.md`\n> documents as breaking — so behaviour is preserved, just expressed declaratively.\n\n### Validate the config locally\n\n```sh\nnpx --yes --package renovate renovate-config-validator renovate.json\n```\n\n---\n\n## 3. Enabling Renovate\n\nTwo ways to run it; **this repo is wired for Option A**.\n\n### Option A — Self-hosted via GitHub Actions (committed in this repo)\n\nThis repo ships [`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml). It runs Renovate\n**every 3 hours during the night window 18:00–06:00 Europe/Berlin**\n(`0 16,19,22,1,4 * * *` UTC, see [Global behaviour](#global-behaviour)) **and** on demand via the **Run workflow** button\n(`workflow_dispatch`, with an optional `dry_run` preview). It authenticates through the existing GitHub\nApp (`APP_ID` / `PRIVATE_KEY` secrets, shared with _04 - Update pnpm Lock_).\n\nTo activate it:\n\n1. Ensure that GitHub App installation grants **contents: write**, **pull-requests: write**,\n **issues: write** (for the Dependency Dashboard), **workflows: write** (so the `github-actions`\n manager may update `.github/workflows/*`), **commit statuses: write**, **Dependabot alerts: read**\n and the mandatory **metadata: read**. Nothing beyond those seven is needed. Changing them at the\n App is only half of it: the installation has to accept the new set, otherwise the runner keeps\n working with the old one and the symptoms below stay. _Alternative:_ replace the app-token step\n with a `RENOVATE_TOKEN` PAT/fine-grained token carrying the same scopes.\n\n > Without **Dependabot alerts: read** every run logs\n > `Cannot access vulnerability alerts`, and `vulnerabilityAlerts` stays inactive; security PRs\n > then only come from `osvVulnerabilityAlerts`.\n\n2. Branch protection. What governs `develop` are **rulesets**, not a classic branch protection\n rule. Keep it that way: a classic rule for the same branch is evaluated on top of the rulesets,\n and its _bypass required pull requests_ list only waives the need to **open** a pull request. It\n does not waive the approval a merge needs, so the bot stays blocked while the list suggests\n otherwise.\n\n A bypass entry always waives **every rule of its ruleset**, never a single one. Hence the split:\n\n | Ruleset | Rules | Bypass list |\n | --------------------- | ---------------------------------------------------------------- | ------------- |\n | `Production branches` | `pull_request` (approvals, code-owner review, merge methods) | `publicuibot` |\n | `Required checks` | `required_status_checks`, restrict deletions, block force pushes | empty |\n\n The runner merges without a human review, but never past a red check. For everyone else nothing\n changes.\n\n Three details that cost an evening on 2026-09-09:\n\n - `allowed_merge_methods` of the `pull_request` rule is `[\"merge\"]`, which is why\n `automergeStrategy` is `merge`. On the repository itself both squash merges and merge commits\n are enabled; the ruleset is what narrows it down.\n - A required status check may never be skipped by a path filter, or the pull request waits\n forever for a status that nothing will post. `codeql.yml` therefore has no `paths-ignore`, and\n `visual-review.yml` answers a skipped CI run with `success` (mode `docs-only`, see\n `scripts/visual-review/resolve-context.mjs`). Anything added to the list has to obey the same\n rule. A red pipeline stops Renovate, which refuses to merge a red branch, but it does not stop\n a human.\n - Every workflow behind a required check needs `synchronize` in its `pull_request` types.\n GitHub wants the check on the **current head commit**, so a workflow that only reacts to\n `opened`/`edited` leaves it unreported after any push and the merge is refused with\n `Required status check \"…\" is expected`. Renovate runs into this on every rebase; that is what\n `pr-title-validation.yml` was missing.\n - A workflow behind a required check that filters `pull_request` by base branch also needs\n `edited`. A stacked pull request opened against a feature branch never matches the filter, and\n when GitHub retargets it to `develop` after the pull request below it is merged, it sends only\n `edited`. Without it the check stays at `Expected — Waiting for status to be reported` until the\n next push. `codeql.yml` therefore reacts to `edited` and runs only when the base changed; a\n title or body edit gets a concurrency group of its own, so it cannot cancel a running analysis.\n - In the target patterns of a ruleset GitHub prefixes `refs/heads/` itself. Enter `release/**/*`,\n never `refs/heads/release/**/*`, otherwise the prefix doubles and the release branches silently\n lose their protection. `gh api repos/public-ui/kolibri/rules/branches/release/3` shows what is\n really in effect.\n\n Repository level, **Settings → General → Pull Requests**: `Allow auto-merge` stays on, Renovate\n uses `platformAutomerge`.\n\n3. Trigger the workflow once via **Run workflow** (optionally with `dry_run` enabled) to verify it, then\n let the nightly schedule take over.\n\n> **Tip:** The `dry_run` input maps to `RENOVATE_DRY_RUN=full`, so the first manual run previews every PR\n> Renovate _would_ open without creating anything.\n\n### Option B — Mend-hosted GitHub App (alternative, zero maintenance)\n\nIf you would rather not self-host, delete `.github/workflows/renovate.yml` and instead:\n\n1. Have an **org admin** install the [Renovate GitHub App](https://github.com/apps/renovate) on\n `public-ui` (or just on `public-ui/kolibri`).\n2. Renovate detects `renovate.json` and opens a Dependency Dashboard issue.\n3. Review the dashboard, then let it run on the weekly schedule.\n\n### Troubleshooting: PRs stay open although CI is green\n\nRenovate never explains a refused merge in the PR itself. The runner log does, but only at\n`LOG_LEVEL=debug`: start the workflow via **Run workflow** with `log_level: debug` (and `dry_run`\noff — a dry run logs `DRY-RUN: Would merge PR` and never sends the request that carries the error).\n\nAt `info` level the only trace is one line per PR:\n\n```\nINFO: All merge attempts failed (repository=public-ui/kolibri, baseBranch=develop, branch=…)\n \"pr\": 10833\n```\n\nIt means Renovate did try. Automerge is configured correctly and the branch is green — GitHub\nrejected the `PUT /repos/:owner/:repo/pulls/:number/merge` call. The cause is therefore always a\nrepository setting or a ruleset, never `renovate.json`. Renovate walks three strategies in order\n(the configured `automergeStrategy` first, then merge commit, then rebase); the debug log holds one\n`Failed to … PR` block per attempt, each with the HTTP status and GitHub's own message:\n\n| Response | Meaning |\n| --------------------------------------------------------- | ------------------------------------------------------------------------- |\n| `405` `Squash merges are not allowed on this repository.` | The merge method is not allowed here — see `allowed_merge_methods` below. |\n| `405` `Rebase merges are not allowed on this repository.` | Same, for rebase. |\n| `405` `Repository rule violations found: …` | A ruleset blocks the bot; the text names the rule. |\n| `405` `… Required status check \"x\" is expected.` | Check `x` never ran on the head commit — see `synchronize` in §3. |\n| `403` `Resource not accessible by integration` | The App lacks **contents: write**. |\n\nWhich rules actually apply to a branch is readable without admin rights:\n\n```sh\ngh api repos/public-ui/kolibri/rules/branches/develop\n```\n\n> **The case of 2026-09-09.** Every green dependency PR sat blocked with `mergeable_state: blocked`\n> while the pipelines were green and no review existed. All three attempts failed with `405`. The\n> two rules behind it both lived in one ruleset that carried everything at once:\n> `allowed_merge_methods: [\"merge\"]` rejected squash and rebase, and `require_last_push_approval`\n> rejected the merge commit, a rule the bot can never satisfy on its own branches because it is\n> always the last pusher. The App was listed in the bypass list of the **classic** branch\n> protection rule, which looks like the fix and is not one: that list only waives the need to open\n> a pull request.\n>\n> What resolved it: the rules were split into the two rulesets described in\n> [§3](#option-a--self-hosted-via-github-actions-committed-in-this-repo), the App went into the\n> bypass list of the one holding the `pull_request` rule, the classic rule was deleted, and\n> `automergeStrategy` moved from `squash` to `merge`. A bypass entry is worth nothing until it sits\n> on the ruleset that actually carries the failing rule, and `bypass_actors` is only readable with\n> admin rights, so the runner log stays the honest source.\n\nTwo more silent failures show up as warnings rather than as a blocked PR:\n\n- `Cannot access vulnerability alerts` — **Dependabot alerts: read** is missing, `vulnerabilityAlerts`\n stays inactive and security PRs come from `osvVulnerabilityAlerts` only.\n- `Could not ensure issue … integration-unauthorized` — the Dependency Dashboard issue is not being\n updated any more. Check **Issues: write** for the App, and whether the issue itself is locked.\n\n---\n\n## 4. Migration checklist (do this only after Renovate is verified)\n\nOnce Renovate runs green for a cycle, retire the overlapping automation to avoid **duplicate PRs**.\nStatus as of the Renovate activation for `develop`:\n\n- [x] Removed `.github/dependabot.yml` (Renovate now manages GitHub Actions — see the\n `github-actions` group).\n- [x] Removed `.github/workflows/auto-dependency-updater.yml` (the daily `ncu` PR job).\n- [x] Dropped the `ncu:*` / `update` scripts and the `npm-check-updates` devDependency from the root\n `package.json`, plus `.ncurc.json`.\n- [ ] Keep `04 - Update pnpm Lock` if you still want a manual lockfile-refresh button; otherwise\n Renovate's `lockFileMaintenance` covers it.\n\nUntil every box is ticked, **leave the existing tooling in place** — Renovate only acts once the\nworkflow (or app) from [§3](#3-enabling-renovate) actually runs, so there is no conflict in the meantime.\n\n---\n\n## 🇩🇪 Zusammenfassung\n\n**Empfehlung: Renovate.** Es ist die einzige Lösung, die das KoliBri-Monorepo in _einer_ Konfiguration\nabbildet — verwandte Pakete gruppieren (z. B. alle `@angular/*`), jeden Adapter-Ordner auf seiner\nfixierten Major-Version halten (`angular/v20|v21`, `react*`), sichere Updates automatisch mergen\n(GitHub Actions, `@types/*`) und alles Riskante (Stencil, kern-ux, ESLint-/Angular-Majors) über das\n**Dependency Dashboard** zur manuellen Freigabe leiten.\n\n- **Dependabot** kann zwar gruppieren, braucht aber pro Paketverzeichnis einen eigenen Eintrag\n (≈30 × 4 Branches) und kann ein Paket nicht _pro Ordner_ auf einer Major-Version halten.\n- **npm-check-updates** ist nur ein CLI ohne eigene Automatisierung (läuft heute im Workflow\n `auto-dependency-updater.yml`).\n\n`automergeStrategy: merge` folgt der Merge-Commit-Konvention des Repos. Renovate läuft auf `develop`\nund dem LTS-Branch `release/4` mit denselben Regeln. `release/1`–`release/3` sind pausiert; ihre\nRegeln stellen sie auf **Security-only**, sobald sie wieder in `baseBranchPatterns` stehen: reguläre\nnpm- und GitHub-Actions-Updates sind dort komplett deaktiviert, Vulnerability-Alert-PRs mergen\n(bei Nicht-Major) automatisch.\n\nDie fertige [`renovate.json`](../renovate.json) liegt im Repo-Root (geprüft mit dem offiziellen\n`renovate-config-validator`), und der self-hosted Runner-Workflow\n[`.github/workflows/renovate.yml`](../.github/workflows/renovate.yml) ist ebenfalls committet.\n**Renovate läuft**, sobald der Workflow startet — nachts alle 3 Stunden zwischen 18:00 und 06:00 Uhr\n(Europe/Berlin) per Zeitplan oder jederzeit manuell über den **Run workflow**-Button (Option A); alternativ kann ein Org-Admin die\n[Renovate-GitHub-App](https://github.com/apps/renovate) installieren (Option B). Bis dahin bleibt die\nbestehende Dependabot-/ncu-Automatisierung zuständig; danach greift die Migrations-Checkliste oben.\n",
525
552
  "kind": "doc"
526
553
  },
527
554
  {
@@ -566,7 +593,7 @@
566
593
  "name": "NEW_COMPONENT",
567
594
  "description": "Projekt starten, wie in Contribution beschrieben.",
568
595
  "path": "docs/tutorials/NEW_COMPONENT.md",
569
- "code": "# Neue Komponente erstellen\n\n> Schritt-für-Schritt-Anleitung basierend auf dem [Skeleton Blueprint](../../packages/components/src/components/_skeleton/ARC42.md).\n\n## Grundprinzipien\n\n- Auflistungen werden immer alphabetisch sortiert\n- Die [ARC42.md](../../packages/components/src/components/_skeleton/ARC42.md) ist die führende Architektur-Spezifikation — lies sie vollständig, bevor du eine neue Komponente erstellst\n- **2-Schichten-Architektur**: Die Web Component ist der Orchestrator — es gibt keine separate Controller/Aspect-Schicht. Nur wirklich wiederverwendbare Logik wird als Behavior (`BaseBehavior`, z.B. `TooltipBehavior`) ausgegliedert\n- Alle Web Components verwenden `shadow: true` — Komponenten ohne Shadow DOM werden als Functional Components implementiert\n- Props leben in `src/internal/props/` mit eigenem `PropDefinition` pro Prop\n- Kein toter Code, keine Barrel-Files, keine `types.ts`\n\n## Checkliste\n\n| Schritt | Kurzbeschreibung |\n| :-----: | ------------------------------------------------------------------------------------------------------------- |\n| 0 | Projekt starten |\n| 1 | Tag-Name in Stencil-Konfiguration registrieren |\n| 2 | Props erstellen oder vorhandene wiederverwenden (`src/internal/props/`) |\n| 3 | API-Definition erstellen (`api.tsx`) mit `PropsConfigShape` und `ApiFromConfig` |\n| 4 | Functional Component erstellen (`component.tsx`) — stateless Renderer mit `BemRootNodeFC` |\n| 5 | Web Component erstellen (`component.tsx`) — erweitert `BaseWebComponent<Api>`, orchestriert alle Logik selbst |\n| 6 | Tests co-lokalisiert neben `component.tsx` erstellen |\n| 7 | Beispiel in React-Sample-App anlegen |\n| 8 | Validierung: `pnpm format && pnpm lint && pnpm --filter @public-ui/components test:unit` |\n\n## Schritt 0 — Projekt starten\n\nProjekt starten, wie in [Contribution](../../CONTRIBUTING.md) beschrieben.\n\n## Schritt 1 — Tag-Name registrieren\n\nDen Tag-Namen der neuen Komponente in `packages/components/stencil.config.ts` registrieren.\n\n## Schritt 2 — Props erstellen (Props-First!)\n\n**Bevor die Komponente implementiert wird, müssen alle Props definiert sein.**\n\nPro Prop eine Datei unter `src/internal/props/`:\n\n```typescript\n// src/internal/props/name.ts\nimport type { SimpleProp } from './helpers/factory';\nimport { createPropDefinition } from './helpers/factory';\nimport { normalizeString } from './helpers/normalizers';\n\nexport type NameProp = SimpleProp<'name', string>;\nexport const nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n- `SimpleProp<K, T>` wenn externer und interner Typ identisch sind\n- `Prop<K, TExternal, TInternal>` wenn sich die Typen unterscheiden (z.B. `ColorProp`)\n- Export in `src/internal/props/index.ts` hinzufügen\n- Bestehende Props aus `index.ts` wiederverwenden, wenn möglich\n\nDetails: [ARC42 §4 — Schema Helper Layer](../../packages/components/src/components/_skeleton/ARC42.md#schema-helper-layer)\n\n## Schritt 3 — API-Definition\n\nDatei: `src/internal/functional-components/<component>/api.tsx`\n\n```typescript\nimport { nameProp } from '../../props';\nimport type { ApiFromConfig, PropsConfigShape } from '../generic-types';\n\nexport const myComponentPropsConfig = {\n\trequired: [nameProp],\n\t// optional: [showProp],\n} as const satisfies PropsConfigShape;\n\nexport type MyComponentApi = ApiFromConfig<\n\ttypeof myComponentPropsConfig,\n\t{\n\t\t// Nur definieren, was die Komponente tatsächlich nutzt:\n\t\t// Callbacks: { click: () => void };\n\t\t// Emitters: { change: string };\n\t\t// Methods: { focus: () => void };\n\t\t// States: { count: number };\n\t\t// Refs: { button: HTMLButtonElement };\n\t\t// Listeners: { keydown: KeyboardEvent };\n\t}\n>;\n```\n\nDetails: [ARC42 §4 — API Definition with PropsConfigShape](../../packages/components/src/components/_skeleton/ARC42.md#api-definition-with-propsconfigshape-and-apifromconfig)\n\n## Schritt 4 — Functional Component\n\nDatei: `src/internal/functional-components/<component>/component.tsx`\n\n```tsx\nimport type { FunctionalComponent as FC } from '@stencil/core';\nimport { h } from '@stencil/core';\nimport { BemRootNodeFC } from '../bem-root-node/component';\nimport type { FunctionalComponentProps } from '../generic-types';\nimport type { MyComponentApi } from './api';\n\nexport const MyComponentFC: FC<FunctionalComponentProps<MyComponentApi>> = ({ name }) => {\n\treturn (\n\t\t<BemRootNodeFC block=\"kol-my-component\">\n\t\t\t<span class=\"kol-my-component__name\">{name}</span>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\n- Stateless, keine Seiteneffekte\n- Genau ein Root-Node via `BemRootNodeFC`: Der `block` und die optionalen `modifiers` werden gegen `KoliBriComponentsBemSchema` in `src/schema/bem-registry.ts` typgeprüft — der Block muss dort **zweifach registriert** sein: im exportierten Typ `KoliBriComponentsBemSchema` (Kompilierung) und im Runtime-`BEM`-Const (konsumiert vom kolibri-cli SCSS-Generator). Nur-Typ-Registrierung kompiliert, bricht aber lautlos die Theme-SCSS-Generierung\n- `BemRootNodeFC` rendert immer ein `<div>` als Root. Für FCs mit anderem semantischem Root (z.B. `<button>`, siehe `ClickButtonFC`) stattdessen `bem.forBlock('kol-xxx')(modifiers)` direkt nutzen\n- Die zugehörige `style.scss` ist Basis-Styling: nur Layout und Struktur, keine Farben (außer dem Schwarz/Weiß-Kontrast-Fallback), keine Abstände und **kein Dark/Light-Color-Scheme** (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Farben und Color Schemes werden ausschließlich im Theme umgesetzt — siehe [Basis-Styling vs. Theming Konzept](../BASE_STYLING_VS_THEMING_CONCEPT.md)\n- Details: [ARC42 §4 — Functional Component Layer](../../packages/components/src/components/_skeleton/ARC42.md#functional-component-layer)\n\n## Schritt 5 — Web Component\n\nDatei: `src/components/<component>/component.tsx`\n\nDie Web Component ist der **Orchestrator**: Sie erweitert `BaseWebComponent<Api>` direkt und absorbiert die gesamte Logik (Prop-Normalisierung, State, Lifecycle) — es gibt keine separate Controller/Aspect-Klasse.\n\n```tsx\nimport type { JSX } from '@stencil/core';\nimport { Component, h, Host, Prop, Watch } from '@stencil/core';\nimport { BaseWebComponent } from '../../internal/functional-components/base-web-component';\nimport type { WebComponentInterface } from '../../internal/functional-components/generic-types';\nimport type { MyComponentApi } from '../../internal/functional-components/my-component/api';\nimport { myComponentPropsConfig } from '../../internal/functional-components/my-component/api';\nimport { MyComponentFC } from '../../internal/functional-components/my-component/component';\nimport { nameProp } from '../../internal/props';\n\n@Component({\n\ttag: 'kol-my-component',\n\tshadow: true,\n})\nexport class KolMyComponent extends BaseWebComponent<MyComponentApi> implements WebComponentInterface<MyComponentApi> {\n\t@Prop()\n\tpublic _name!: string;\n\n\t@Watch('_name')\n\tpublic watchName(value?: string): void {\n\t\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\tthis.initRenderProps(myComponentPropsConfig);\n\t\tthis.watchName(this._name);\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<MyComponentFC name={this.getRenderProp('name')} />\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n- `componentWillLoad()` ruft zuerst `this.initRenderProps(propsConfig)` auf und wendet danach alle Props an (Prop-Dreieck: Deklaration, `@Watch()`, Init)\n- Watcher rufen die Prop-Factory direkt auf: `nameProp.apply(value, (v) => this.setRenderProp('name', v))`\n- `@State`-Felder werden über `this.setState(key, value)` / `this.getState(key)` verwaltet und im `render()` direkt übergeben\n- Immer `shadow: true` und `<Host>` ohne Klassen-Attribut\n- `@Watch` nur auf unterstrichene Props\n- Wiederverwendbare Logik für mehrere Komponenten wird als Behavior ausgegliedert (`BaseBehavior`, z.B. `TooltipBehavior`): `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)` — Details: [ARC42 §4 — Behavior Layer](../../packages/components/src/components/_skeleton/ARC42.md#behavior-layer)\n- Details: [ARC42 §4 — Web Component Layer](../../packages/components/src/components/_skeleton/ARC42.md#web-component-layer)\n\nWenn ein Behavior garantiert kein `@State` benötigt, verwende den Sentinel:\n\n```typescript\nprivate readonly myBehavior = new MyBehavior(BaseWebComponent.stateLess);\n```\n\n## Schritt 6 — Tests\n\nTests liegen **direkt neben** `component.tsx` — kein `test/`-Unterordner.\n\n**Snapshot-Test** (`snapshot.spec.tsx`):\n\n```tsx\nimport { executeSnapshotTests } from '../../utils/testing';\nimport { KolMyComponent } from './component';\n\nconst TAG = 'kol-my-component';\n\ntype Props = {\n\t_name: string;\n};\n\nexecuteSnapshotTests<Props>(TAG, [KolMyComponent], [{ _name: 'Test' }, { _name: '' }]);\n```\n\n**Interaction-Test** (`interaction.e2e.ts`):\n\n```typescript\nimport { expect } from '@playwright/test';\nimport { test } from '@stencil/playwright';\n\ntest.describe('kol-my-component', () => {\n\ttest.beforeEach(async ({ page }) => {\n\t\tawait page.setContent('<kol-my-component _name=\"Test\"></kol-my-component>');\n\t});\n\n\ttest('should render the name', async ({ page }) => {\n\t\tawait expect(page.locator('kol-my-component')).toBeVisible();\n\t});\n});\n```\n\nDetails: [ARC42 §9 — Design Decision 11](../../packages/components/src/components/_skeleton/ARC42.md#9-design-decisions)\n\n## Schritt 7 — Beispiel in React-Sample-App\n\nDatei: `packages/samples/react/src/scenarios/<component>.tsx`\n\nAnschließend die Route in `packages/samples/react/src/scenarios/routes.ts` registrieren.\n\nZum Testen:\n\n```bash\ncd packages/samples/presentation\npnpm dev\n# Navigiere zu http://localhost:9191\n```\n\n## Schritt 8 — Validierung\n\n```bash\npnpm format # ~10 Sekunden\npnpm lint # ~1 Minute, NICHT abbrechen\npnpm --filter @public-ui/components test:unit # ~2-3 Minuten, NICHT abbrechen\n```\n\nAlle drei Befehle müssen fehlerfrei durchlaufen.\n\n## Referenz\n\nDie vollständige Referenzimplementierung findet sich im Skeleton Blueprint:\n\n- **Architektur**: [`_skeleton/ARC42.md`](../../packages/components/src/components/_skeleton/ARC42.md)\n- **Agent-Instruktionen**: [`_skeleton/AGENTS.md`](../../packages/components/src/components/_skeleton/AGENTS.md)\n- **Refactoring-Leitfaden**: [`_skeleton/REFACTORING_PROMPT.md`](../../packages/components/src/components/_skeleton/REFACTORING_PROMPT.md)\n",
596
+ "code": "# Neue Komponente erstellen\n\n> Schritt-für-Schritt-Anleitung basierend auf dem [Skeleton Blueprint](../../packages/components/docs/ARC42-SKELETON.md).\n\n## Grundprinzipien\n\n- Auflistungen werden immer alphabetisch sortiert\n- Die [ARC42.md](../../packages/components/docs/ARC42-SKELETON.md) ist die führende Architektur-Spezifikation — lies sie vollständig, bevor du eine neue Komponente erstellst\n- **2-Schichten-Architektur**: Die Web Component ist der Orchestrator — es gibt keine separate Controller/Aspect-Schicht. Nur wirklich wiederverwendbare Logik wird als Behavior (`BaseBehavior`, z.B. `TooltipBehavior`) ausgegliedert\n- Alle Web Components verwenden `shadow: true` — Komponenten ohne Shadow DOM werden als Functional Components implementiert\n- Props leben in `src/internal/props/` mit eigenem `PropDefinition` pro Prop\n- Kein toter Code, keine Barrel-Files, keine `types.ts`\n\n## Checkliste\n\n| Schritt | Kurzbeschreibung |\n| :-----: | ------------------------------------------------------------------------------------------------------------- |\n| 0 | Projekt starten |\n| 1 | Tag-Name in Stencil-Konfiguration registrieren |\n| 2 | Props erstellen oder vorhandene wiederverwenden (`src/internal/props/`) |\n| 3 | API-Definition erstellen (`api.tsx`) mit `PropsConfigShape` und `ApiFromConfig` |\n| 4 | Functional Component erstellen (`component.tsx`) — stateless Renderer mit `BemRootNodeFC` |\n| 5 | Web Component erstellen (`component.tsx`) — erweitert `BaseWebComponent<Api>`, orchestriert alle Logik selbst |\n| 6 | Tests co-lokalisiert neben `component.tsx` erstellen |\n| 7 | Beispiel in React-Sample-App anlegen |\n| 8 | Validierung: `pnpm format && pnpm lint && pnpm --filter @public-ui/components test:unit` |\n\n## Schritt 0 — Projekt starten\n\nProjekt starten, wie in [Contribution](../../CONTRIBUTING.md) beschrieben.\n\n## Schritt 1 — Tag-Name registrieren\n\nDen Tag-Namen der neuen Komponente in `packages/components/stencil.config.ts` registrieren.\n\n## Schritt 2 — Props erstellen (Props-First!)\n\n**Bevor die Komponente implementiert wird, müssen alle Props definiert sein.**\n\nPro Prop eine Datei unter `src/internal/props/`:\n\n```typescript\n// src/internal/props/name.ts\nimport type { SimpleProp } from './helpers/factory';\nimport { createPropDefinition } from './helpers/factory';\nimport { normalizeString } from './helpers/normalizers';\n\nexport type NameProp = SimpleProp<'name', string>;\nexport const nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n- `SimpleProp<K, T>` wenn externer und interner Typ identisch sind\n- `Prop<K, TExternal, TInternal>` wenn sich die Typen unterscheiden (z.B. `ColorProp`)\n- Export in `src/internal/props/index.ts` hinzufügen\n- Bestehende Props aus `index.ts` wiederverwenden, wenn möglich\n\nDetails: [ARC42 §4 — Schema Helper Layer](../../packages/components/docs/ARC42-SKELETON.md#schema-helper-layer)\n\n## Schritt 3 — API-Definition\n\nDatei: `src/internal/functional-components/<component>/api.tsx`\n\n```typescript\nimport { nameProp } from '../../props';\nimport type { ApiFromConfig, PropsConfigShape } from '../generic-types';\n\nexport const myComponentPropsConfig = {\n\trequired: [nameProp],\n\t// optional: [showProp],\n} as const satisfies PropsConfigShape;\n\nexport type MyComponentApi = ApiFromConfig<\n\ttypeof myComponentPropsConfig,\n\t{\n\t\t// Nur definieren, was die Komponente tatsächlich nutzt:\n\t\t// Callbacks: { click: () => void };\n\t\t// Emitters: { change: string };\n\t\t// Methods: { focus: () => void };\n\t\t// States: { count: number };\n\t\t// Refs: { button: HTMLButtonElement };\n\t\t// Listeners: { keydown: KeyboardEvent };\n\t}\n>;\n```\n\nDetails: [ARC42 §4 — API Definition with PropsConfigShape](../../packages/components/docs/ARC42-SKELETON.md#api-definition-with-propsconfigshape-and-apifromconfig)\n\n## Schritt 4 — Functional Component\n\nDatei: `src/internal/functional-components/<component>/component.tsx`\n\n```tsx\nimport type { FunctionalComponent as FC } from '@stencil/core';\nimport { h } from '@stencil/core';\nimport { BemRootNodeFC } from '../bem-root-node/component';\nimport type { FunctionalComponentProps } from '../generic-types';\nimport type { MyComponentApi } from './api';\n\nexport const MyComponentFC: FC<FunctionalComponentProps<MyComponentApi>> = ({ name }) => {\n\treturn (\n\t\t<BemRootNodeFC block=\"kol-my-component\">\n\t\t\t<span class=\"kol-my-component__name\">{name}</span>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\n- Stateless, keine Seiteneffekte\n- Genau ein Root-Node via `BemRootNodeFC`: Der `block` und die optionalen `modifiers` werden gegen `KoliBriComponentsBemSchema` in `src/schema/bem-registry.ts` typgeprüft — der Block muss dort **zweifach registriert** sein: im exportierten Typ `KoliBriComponentsBemSchema` (Kompilierung) und im Runtime-`BEM`-Const (konsumiert vom kolibri-cli SCSS-Generator). Nur-Typ-Registrierung kompiliert, bricht aber lautlos die Theme-SCSS-Generierung\n- `BemRootNodeFC` rendert immer ein `<div>` als Root. Für FCs mit anderem semantischem Root (z.B. `<button>`, siehe `ClickButtonFC`) stattdessen `bem.forBlock('kol-xxx')(modifiers)` direkt nutzen\n- Die zugehörige `style.scss` ist Basis-Styling: nur Layout und Struktur, keine Farben (außer dem Schwarz/Weiß-Kontrast-Fallback), keine Abstände und **kein Dark/Light-Color-Scheme** (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Farben und Color Schemes werden ausschließlich im Theme umgesetzt — siehe [Basis-Styling vs. Theming Konzept](../BASE_STYLING_VS_THEMING_CONCEPT.md)\n- Details: [ARC42 §4 — Functional Component Layer](../../packages/components/docs/ARC42-SKELETON.md#functional-component-layer)\n\n## Schritt 5 — Web Component\n\nDatei: `src/components/<component>/component.tsx`\n\nDie Web Component ist der **Orchestrator**: Sie erweitert `BaseWebComponent<Api>` direkt und absorbiert die gesamte Logik (Prop-Normalisierung, State, Lifecycle) — es gibt keine separate Controller/Aspect-Klasse.\n\n```tsx\nimport type { JSX } from '@stencil/core';\nimport { Component, h, Host, Prop, Watch } from '@stencil/core';\nimport { BaseWebComponent } from '../../internal/functional-components/base-web-component';\nimport type { PropsConfigShape, WebComponentInterface } from '../../internal/functional-components/generic-types';\nimport type { MyComponentApi } from '../../internal/functional-components/my-component/api';\nimport { myComponentPropsConfig } from '../../internal/functional-components/my-component/api';\nimport { MyComponentFC } from '../../internal/functional-components/my-component/component';\nimport { nameProp } from '../../internal/props';\n\n@Component({\n\ttag: 'kol-my-component',\n\tshadow: true,\n})\nexport class KolMyComponent extends BaseWebComponent<MyComponentApi> implements WebComponentInterface<MyComponentApi> {\n\tprotected readonly propsConfig: PropsConfigShape = myComponentPropsConfig;\n\n\t@Prop()\n\tpublic _name!: string;\n\n\t@Watch('_name')\n\tpublic watchName(value?: string): void {\n\t\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\tthis.watchName(this._name);\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<MyComponentFC name={this.getRenderProp('name')} />\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n- Die Basis säht die Render-Props aus dem `propsConfig`-Feld beim ersten Zugriff — auch wenn ein `@Watch` durch eine Prop-Zuweisung vor `componentWillLoad()` feuert; `componentWillLoad()` wendet alle Props an (Prop-Dreieck: Deklaration, `@Watch()`, Init)\n- Watcher rufen die Prop-Factory direkt auf: `nameProp.apply(value, (v) => this.setRenderProp('name', v))`\n- `@State`-Felder werden über `this.setState(key, value)` / `this.getState(key)` verwaltet und im `render()` direkt übergeben\n- Immer `shadow: true` und `<Host>` ohne Klassen-Attribut\n- `@Watch` nur auf unterstrichene Props\n- Wiederverwendbare Logik für mehrere Komponenten wird als Behavior ausgegliedert (`BaseBehavior`, z.B. `TooltipBehavior`): `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)` — Details: [ARC42 §4 — Behavior Layer](../../packages/components/docs/ARC42-SKELETON.md#behavior-layer)\n- Details: [ARC42 §4 — Web Component Layer](../../packages/components/docs/ARC42-SKELETON.md#web-component-layer)\n\nWenn ein Behavior garantiert kein `@State` benötigt, verwende den Sentinel:\n\n```typescript\nprivate readonly myBehavior = new MyBehavior(BaseWebComponent.stateLess);\n```\n\n## Schritt 6 — Tests\n\nTests liegen **direkt neben** `component.tsx` — kein `test/`-Unterordner.\n\n**Snapshot-Test** (`snapshot.spec.tsx`):\n\n```tsx\nimport { executeSnapshotTests } from '../../utils/testing';\nimport { KolMyComponent } from './component';\n\nconst TAG = 'kol-my-component';\n\ntype Props = {\n\t_name: string;\n};\n\nexecuteSnapshotTests<Props>(TAG, [KolMyComponent], [{ _name: 'Test' }, { _name: '' }]);\n```\n\n**Interaction-Test** (`interaction.e2e.ts`):\n\n```typescript\nimport { expect } from '@playwright/test';\nimport { test } from '@stencil/playwright';\n\ntest.describe('kol-my-component', () => {\n\ttest.beforeEach(async ({ page }) => {\n\t\tawait page.setContent('<kol-my-component _name=\"Test\"></kol-my-component>');\n\t});\n\n\ttest('should render the name', async ({ page }) => {\n\t\tawait expect(page.locator('kol-my-component')).toBeVisible();\n\t});\n});\n```\n\nDetails: [ARC42 §9 — Design Decision 11](../../packages/components/docs/ARC42-SKELETON.md#9-design-decisions)\n\n## Schritt 7 — Beispiel in React-Sample-App\n\nDatei: `packages/samples/react/src/scenarios/<component>.tsx`\n\nAnschließend die Route in `packages/samples/react/src/scenarios/routes.ts` registrieren.\n\nZum Testen:\n\n```bash\ncd packages/samples/presentation\npnpm dev\n# Navigiere zu http://localhost:9191\n```\n\n## Schritt 8 — Validierung\n\n```bash\npnpm format # ~10 Sekunden\npnpm lint # ~1 Minute, NICHT abbrechen\npnpm --filter @public-ui/components test:unit # ~2-3 Minuten, NICHT abbrechen\n```\n\nAlle drei Befehle müssen fehlerfrei durchlaufen.\n\n## Referenz\n\nDie vollständige Referenzimplementierung findet sich im Skeleton Blueprint:\n\n- **Architektur**: [`ARC42-SKELETON.md`](../../packages/components/docs/ARC42-SKELETON.md)\n",
570
597
  "kind": "doc"
571
598
  },
572
599
  {
@@ -840,11 +867,10 @@
840
867
  "description": "This story demonstrates the expert slot feature of KolButton. The expert slot allows you to insert custom content into the button, providing advanced customization options beyond the standard label and icon properties.",
841
868
  "tags": [
842
869
  "kol-button",
843
- "kol-icon",
844
- "kol-tooltip"
870
+ "kol-icon"
845
871
  ],
846
872
  "path": "packages/samples/react/src/components/button/expert-slot.tsx",
847
- "code": "import { KolButton, KolIcon } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { useAlert } from '../../hooks/useAlert';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nimport './expert-slot.tooltip.scss';\n\nconst KolTooltip = 'kol-tooltip-wc' as unknown as React.FC<{ _label: string }>;\n\nexport const ButtonExpertSlot: FC = () => {\n\tconst { dummyClickEventHandler } = useAlert();\n\n\tconst dummyEventHandler = {\n\t\tonClick: dummyClickEventHandler,\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis story demonstrates the expert slot feature of KolButton. The expert slot allows you to insert custom content into the button, providing advanced\n\t\t\t\t\tcustomization options beyond the standard label and icon properties.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-8\">\n\t\t\t\t<SampleBlock id=\"buttons-expert-slot-content\" heading=\"Buttons with Expert Slot Content\" fitContent>\n\t\t\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-house\" _label=\"\" _variant=\"primary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">I am more than just a button</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-kolibri\" _label=\"\" _variant=\"secondary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Custom content here</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-alert-warning\" _label=\"\" _variant=\"danger\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Delete with custom text</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _label=\"\" _variant=\"danger\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<KolIcon _icons=\"kolicon-alert-warning\" _label=\"Delete with custom text\" slot=\"expert\" />\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolTooltip _label=\"Delete with custom text\" />\n\t\t\t\t\t</div>\n\t\t\t\t</SampleBlock>\n\n\t\t\t\t<SampleBlock id=\"disabled-buttons-expert-slot\" heading=\"Disabled Buttons with Expert Slot\" fitContent>\n\t\t\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t\t\t<KolButton _disabled _icons=\"kolicon-house\" _label=\"\" _variant=\"primary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Disabled expert slot</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _disabled _icons=\"kolicon-eye-closed\" _label=\"\" _variant=\"ghost\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Another disabled one</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t</div>\n\t\t\t\t</SampleBlock>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
873
+ "code": "import { KolButton, KolIcon } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { useAlert } from '../../hooks/useAlert';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const ButtonExpertSlot: FC = () => {\n\tconst { dummyClickEventHandler } = useAlert();\n\n\tconst dummyEventHandler = {\n\t\tonClick: dummyClickEventHandler,\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis story demonstrates the expert slot feature of KolButton. The expert slot allows you to insert custom content into the button, providing advanced\n\t\t\t\t\tcustomization options beyond the standard label and icon properties.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-8\">\n\t\t\t\t<SampleBlock id=\"buttons-expert-slot-content\" heading=\"Buttons with Expert Slot Content\" fitContent>\n\t\t\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-house\" _label=\"\" _variant=\"primary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">I am more than just a button</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-kolibri\" _label=\"\" _variant=\"secondary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Custom content here</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _icons=\"kolicon-alert-warning\" _label=\"\" _variant=\"danger\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Delete with custom text</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _label=\"\" _variant=\"danger\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<KolIcon _icons=\"kolicon-alert-warning\" _label=\"Delete with custom text\" slot=\"expert\" />\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t</div>\n\t\t\t\t</SampleBlock>\n\n\t\t\t\t<SampleBlock id=\"disabled-buttons-expert-slot\" heading=\"Disabled Buttons with Expert Slot\" fitContent>\n\t\t\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t\t\t<KolButton _disabled _icons=\"kolicon-house\" _label=\"\" _variant=\"primary\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Disabled expert slot</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t\t<KolButton _disabled _icons=\"kolicon-eye-closed\" _label=\"\" _variant=\"ghost\" _on={dummyEventHandler}>\n\t\t\t\t\t\t\t<span slot=\"expert\">Another disabled one</span>\n\t\t\t\t\t\t</KolButton>\n\t\t\t\t\t</div>\n\t\t\t\t</SampleBlock>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
848
874
  "kind": "sample"
849
875
  },
850
876
  {
@@ -1107,7 +1133,7 @@
1107
1133
  "kol-dialog"
1108
1134
  ],
1109
1135
  "path": "packages/samples/react/src/components/dialog/with-alert.tsx",
1110
- "code": "import type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\n\nimport { KolAlert, KolButton, KolDialog } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\n/**\n * Demonstrates that closing a KolAlert inside a KolDialog does NOT trigger\n * the dialog's onClose callback (regression test for issue #9541).\n */\nexport const DialogWithAlert: FC = () => {\n\tconst dialogRef = useRef<HTMLKolDialogElement>(null);\n\tconst [log, setLog] = useState<string[]>([]);\n\tconst [showAlert, setShowAlert] = useState(true);\n\n\tconst appendLog = (msg: string) => setLog((prev) => [...prev, `${new Date().toLocaleTimeString()} – ${msg}`]);\n\n\tconst onOpenDialog = {\n\t\tonClick: () => {\n\t\t\tsetShowAlert(true);\n\t\t\tdialogRef.current?.showModal();\n\t\t},\n\t};\n\n\tconst onDialogClose = () => {\n\t\tappendLog('Dialog onClose fired');\n\t};\n\n\tconst onAlertClose = () => {\n\t\tappendLog('Alert onClose fired');\n\t\tsetShowAlert(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tClosing the <strong>KolAlert</strong> inside the dialog must <em>not</em> trigger the dialog&apos;s <code>onClose</code> callback. Only closing the\n\t\t\t\t\tdialog itself (via the card closer or <code>close()</code>) should fire that callback.\n\t\t\t\t</p>\n\t\t\t\t<p>\n\t\t\t\t\tWatch the event log below: after clicking the alert closer you should see <em>only</em> &quot;Alert onClose fired&quot;, not &quot;Dialog onClose\n\t\t\t\t\tfired&quot;.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<div>\n\t\t\t\t\t<KolButton _label=\"Open dialog with alert\" _on={onOpenDialog} />\n\t\t\t\t\t<KolDialog ref={dialogRef} _label=\"Dialog with KolAlert inside\" _variant=\"card\" _width=\"40%\" _on={{ onClose: onDialogClose }}>\n\t\t\t\t\t\t<div className=\"p-4\">\n\t\t\t\t\t\t\t{showAlert && (\n\t\t\t\t\t\t\t\t<KolAlert _label=\"Closeable alert\" _type=\"info\" _variant=\"card\" _hasCloser _on={{ onClose: onAlertClose }}>\n\t\t\t\t\t\t\t\t\tClose this alert – the dialog must stay open and its onClose must NOT fire.\n\t\t\t\t\t\t\t\t</KolAlert>\n\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t{!showAlert && <p>Alert was closed. The dialog is still open – correct behaviour!</p>}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</KolDialog>\n\t\t\t\t</div>\n\n\t\t\t\t{log.length > 0 && (\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<strong>Event log:</strong>\n\t\t\t\t\t\t<ul>\n\t\t\t\t\t\t\t{log.map((entry, i) => (\n\t\t\t\t\t\t\t\t<li key={i}>{entry}</li>\n\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t</ul>\n\t\t\t\t\t</div>\n\t\t\t\t)}\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
1136
+ "code": "import type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\n\nimport { KolAlert, KolButton, KolDialog } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\n/**\n * Demonstrates that closing a KolAlert inside a KolDialog does NOT trigger\n * the dialog's onClose callback (regression test for issue #9541).\n */\nexport const DialogWithAlert: FC = () => {\n\tconst dialogRef = useRef<HTMLKolDialogElement>(null);\n\tconst [log, setLog] = useState<string[]>([]);\n\tconst [showAlert, setShowAlert] = useState(true);\n\n\tconst appendLog = (msg: string) => setLog((prev) => [...prev, `${new Date().toLocaleTimeString()} – ${msg}`]);\n\n\tconst onOpenDialog = {\n\t\tonClick: () => {\n\t\t\tsetShowAlert(true);\n\t\t\tdialogRef.current?.showModal();\n\t\t},\n\t};\n\n\tconst onDialogClose = () => {\n\t\tappendLog('Dialog onClose fired');\n\t};\n\n\tconst onAlertClose = () => {\n\t\tappendLog('Alert onClose fired');\n\t\tsetShowAlert(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tClosing the <strong>KolAlert</strong> inside the dialog must <em>not</em> trigger the dialog&apos;s <code>onClose</code> callback. Only closing the\n\t\t\t\t\tdialog itself (via the card closer or <code>close()</code>) should fire that callback.\n\t\t\t\t</p>\n\t\t\t\t<p>\n\t\t\t\t\tWatch the event log below: after clicking the alert closer you should see <em>only</em> &quot;Alert onClose fired&quot;, not &quot;Dialog onClose\n\t\t\t\t\tfired&quot;.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<div>\n\t\t\t\t\t<KolButton _label=\"Open dialog with alert\" _on={onOpenDialog} />\n\t\t\t\t\t<KolDialog\n\t\t\t\t\t\tref={dialogRef}\n\t\t\t\t\t\t_label=\"Dialog with KolAlert inside\"\n\t\t\t\t\t\t_variant=\"card\"\n\t\t\t\t\t\t_width=\"40%\"\n\t\t\t\t\t\t_on={{ onToggle: (open) => console.log('Dialog onToggle triggered!', open), onClose: onDialogClose }}\n\t\t\t\t\t>\n\t\t\t\t\t\t<div className=\"p-4\">\n\t\t\t\t\t\t\t{showAlert && (\n\t\t\t\t\t\t\t\t<KolAlert _label=\"Closeable alert\" _type=\"info\" _variant=\"card\" _hasCloser _on={{ onClose: onAlertClose }}>\n\t\t\t\t\t\t\t\t\tClose this alert – the dialog must stay open and its onClose must NOT fire.\n\t\t\t\t\t\t\t\t</KolAlert>\n\t\t\t\t\t\t\t)}\n\t\t\t\t\t\t\t{!showAlert && <p>Alert was closed. The dialog is still open – correct behaviour!</p>}\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</KolDialog>\n\t\t\t\t</div>\n\n\t\t\t\t{log.length > 0 && (\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<strong>Event log:</strong>\n\t\t\t\t\t\t<ul>\n\t\t\t\t\t\t\t{log.map((entry, i) => (\n\t\t\t\t\t\t\t\t<li key={i}>{entry}</li>\n\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t</ul>\n\t\t\t\t\t</div>\n\t\t\t\t)}\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
1111
1137
  "kind": "sample"
1112
1138
  },
1113
1139
  {
@@ -1743,7 +1769,7 @@
1743
1769
  "id": "sample/input-text/aria-details",
1744
1770
  "group": "input-text",
1745
1771
  "name": "aria-details",
1746
- "description": "Demonstrates how to use _ariaDetails to reference an external element that provides detailed information about form inputs. All inputs below reference the same details box via their _ariaDetails prop. The _ariaDetails prop uses ElementInternals.ariaDetailsElements to cross the Shadow DOM boundary…",
1772
+ "description": "Demonstrates how to use _ariaDetails to reference an external element that provides detailed information about form inputs. All inputs below reference the same details box via their _ariaDetails prop. The native inputs above are the control group: the first one declares a plain aria-details IDREF…",
1747
1773
  "tags": [
1748
1774
  "kol-combobox",
1749
1775
  "kol-input-text",
@@ -1751,7 +1777,7 @@
1751
1777
  "kol-textarea"
1752
1778
  ],
1753
1779
  "path": "packages/samples/react/src/components/input-text/aria-details.tsx",
1754
- "code": "import { KolCombobox, KolInputText, KolSelect, KolTextarea } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const InputTextAriaDetails: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tDemonstrates how to use <code>_ariaDetails</code> to reference an external element that provides detailed information about form inputs. All inputs\n\t\t\t\tbelow reference the same details box via their <code>_ariaDetails</code> prop.\n\t\t\t</p>\n\t\t\t<p>\n\t\t\t\tThe <code>_ariaDetails</code> prop uses <code>ElementInternals.ariaDetailsElements</code> to cross the Shadow DOM boundary, making it accessible to\n\t\t\t\tscreen readers. This works across all form input components: input-text, select, textarea, and combobox.\n\t\t\t</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"aria-details\" className=\"grid gap-8\">\n\t\t\t{/* Input Form with all 4 components */}\n\t\t\t<div className=\"grid gap-4 p-4 border border-gray-300 rounded\">\n\t\t\t\t<h2 className=\"text-lg font-semibold\">Form Inputs with Shared Details</h2>\n\n\t\t\t\t<KolInputText _label=\"Email Address\" _ariaDetails=\"details-box\" _placeholder=\"user@example.com\" _hint=\"We'll never share your email\" />\n\n\t\t\t\t<KolSelect\n\t\t\t\t\t_label=\"Country\"\n\t\t\t\t\t_ariaDetails=\"details-box\"\n\t\t\t\t\t_options={[\n\t\t\t\t\t\t{ label: 'Germany', value: 'de' },\n\t\t\t\t\t\t{ label: 'Austria', value: 'at' },\n\t\t\t\t\t\t{ label: 'Switzerland', value: 'ch' },\n\t\t\t\t\t]}\n\t\t\t\t/>\n\n\t\t\t\t<KolTextarea _label=\"Message\" _ariaDetails=\"details-box\" _placeholder=\"Enter your message here...\" _rows={4} />\n\n\t\t\t\t<KolCombobox _label=\"Favorite Language\" _ariaDetails=\"details-box\" _suggestions={['TypeScript', 'JavaScript', 'Python', 'Go', 'Rust', 'Java']} />\n\t\t\t</div>\n\n\t\t\t{/* Shared details box */}\n\t\t\t<div id=\"details-box\" className=\"p-4 bg-blue-50 border-l-4 border-blue-400 rounded\" role=\"complementary\">\n\t\t\t\t<h3 className=\"font-semibold text-blue-900 mb-2\">💡 Form Details</h3>\n\t\t\t\t<ul className=\"text-sm text-blue-800 space-y-2\">\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Email:</strong> Please enter a valid email address. We use this to contact you about your submission.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Country:</strong> Select your country of residence. This helps us provide localized support.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Message:</strong> Provide as much detail as possible. The more information you give, the better we can assist you.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Language:</strong> Choose your preferred programming language. This helps us recommend relevant resources.\n\t\t\t\t\t</li>\n\t\t\t\t</ul>\n\t\t\t</div>\n\t\t</SampleBlock>\n\t</>\n);\n",
1780
+ "code": "import { KolCombobox, KolInputText, KolSelect, KolTextarea } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport '../../@shared/demo-input-wc';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nexport const InputTextAriaDetails: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tDemonstrates how to use <code>_ariaDetails</code> to reference an external element that provides detailed information about form inputs. All inputs\n\t\t\t\tbelow reference the same details box via their <code>_ariaDetails</code> prop.\n\t\t\t</p>\n\t\t\t<p>\n\t\t\t\tThe native inputs above are the control group: the first one declares a plain <code>aria-details</code> IDREF in the same tree, the second one is\n\t\t\t\twrapped in a native web component whose shadow input bridges the reference via <code>ariaDetailsElements</code> — the same mechanism KoliBri uses. If a\n\t\t\t\tnative case announces the details in a screen reader while the KoliBri fields do not, the gap is in KoliBri; if the native shadow case is silent too,\n\t\t\t\tthe platform does not support the relation across the boundary yet (Safari/VoiceOver lacks element reflection — verify with NVDA or JAWS on Chromium\n\t\t\t\tinstead).\n\t\t\t</p>\n\t\t\t<p>\n\t\t\t\tThe last example below replicates the{' '}\n\t\t\t\t<a href=\"https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details\">\n\t\t\t\t\tMDN example for <code>aria-details</code>\n\t\t\t\t</a>\n\t\t\t\t: a term references its definition and an explanatory link — the canonical use outside of forms the attribute was designed for.\n\t\t\t</p>\n\t\t</SampleDescription>\n\n\t\t<SampleBlock id=\"aria-details\" className=\"grid gap-8\">\n\t\t\t{/* Native reference implementations — the control group */}\n\t\t\t<div className=\"grid gap-4 p-4 border border-gray-300 rounded\">\n\t\t\t\t<h2 className=\"text-lg font-semibold\">Native reference implementations</h2>\n\n\t\t\t\t<div>\n\t\t\t\t\t<label className=\"block\">\n\t\t\t\t\t\t<span className=\"block mb-2\">Native HTML input (no web component)</span>\n\t\t\t\t\t\t<input aria-details=\"details-box-native-light\" aria-label=\"Native light input\" className=\"border border-gray-500 p-2\" />\n\t\t\t\t\t</label>\n\t\t\t\t\t<div id=\"details-box-native-light\" className=\"mt-2 p-2 bg-blue-50 border-l-4 border-blue-400 rounded text-sm text-blue-800\">\n\t\t\t\t\t\tDetails for the plain native input: the IDREF resolves in the same tree — no boundary to cross.\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\n\t\t\t\t<div>{React.createElement('demo-input-light', { 'aria-details': 'details-box-native-light' })}</div>\n\n\t\t\t\t<div>\n\t\t\t\t\t{React.createElement('demo-input-shadow', { 'aria-details': 'details-box-native-shadow' })}\n\t\t\t\t\t<div id=\"details-box-native-shadow\" className=\"mt-2 p-2 bg-blue-50 border-l-4 border-blue-400 rounded text-sm text-blue-800\">\n\t\t\t\t\t\tDetails for the native shadow input: the reference crosses the boundary via <code>ariaDetailsElements</code> on the input.\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* KoliBri form fields */}\n\t\t\t<div className=\"grid gap-4 p-4 border border-gray-300 rounded\">\n\t\t\t\t<h2 className=\"text-lg font-semibold\">Form Inputs with Shared Details</h2>\n\n\t\t\t\t<KolInputText _label=\"Email Address\" _ariaDetails=\"details-box\" _placeholder=\"user@example.com\" _hint=\"We'll never share your email\" />\n\n\t\t\t\t<KolSelect\n\t\t\t\t\t_label=\"Country\"\n\t\t\t\t\t_ariaDetails=\"details-box\"\n\t\t\t\t\t_options={[\n\t\t\t\t\t\t{ label: 'Germany', value: 'de' },\n\t\t\t\t\t\t{ label: 'Austria', value: 'at' },\n\t\t\t\t\t\t{ label: 'Switzerland', value: 'ch' },\n\t\t\t\t\t]}\n\t\t\t\t/>\n\n\t\t\t\t<KolTextarea _label=\"Message\" _ariaDetails=\"details-box\" _placeholder=\"Enter your message here...\" _rows={4} />\n\n\t\t\t\t<KolCombobox _label=\"Favorite Language\" _ariaDetails=\"details-box\" _suggestions={['TypeScript', 'JavaScript', 'Python', 'Go', 'Rust', 'Java']} />\n\t\t\t</div>\n\n\t\t\t{/* Shared details box */}\n\t\t\t<div id=\"details-box\" className=\"p-4 bg-blue-50 border-l-4 border-blue-400 rounded\" role=\"complementary\">\n\t\t\t\t<h3 className=\"font-semibold text-blue-900 mb-2\">💡 Form Details</h3>\n\t\t\t\t<ul className=\"text-sm text-blue-800 space-y-2\">\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Email:</strong> Please enter a valid email address. We use this to contact you about your submission.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Country:</strong> Select your country of residence. This helps us provide localized support.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Message:</strong> Provide as much detail as possible. The more information you give, the better we can assist you.\n\t\t\t\t\t</li>\n\t\t\t\t\t<li>\n\t\t\t\t\t\t<strong>Language:</strong> Choose your preferred programming language. This helps us recommend relevant resources.\n\t\t\t\t\t</li>\n\t\t\t\t</ul>\n\t\t\t</div>\n\n\t\t\t{/* MDN example — term & definition (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-details) */}\n\t\t\t<div className=\"grid gap-4 p-4 border border-gray-300 rounded\">\n\t\t\t\t<h2 className=\"text-lg font-semibold\">MDN example: term &amp; definition</h2>\n\n\t\t\t\t<p>\n\t\t\t\t\tThe term below references two targets: the definition paragraph and the explanatory image link. Screen reader support for <code>aria-details</code> is\n\t\t\t\t\theavily fragmented — check <a href=\"https://a11ysupport.io/tech/aria/aria-details_attribute\">a11ysupport.io</a> before relying on it.\n\t\t\t\t</p>\n\n\t\t\t\t<p>\n\t\t\t\t\tThe <strong>cubic-bezier()</strong> functional notation defines a cubic{' '}\n\t\t\t\t\t<span role=\"term\" aria-details=\"bezier bezImg\" className=\"underline decoration-dotted underline-offset-4\">\n\t\t\t\t\t\tBézier curve\n\t\t\t\t\t</span>\n\t\t\t\t\t. As these curves are continuous, they are often used to smooth down the start and end of the curve and are therefore sometimes called easing\n\t\t\t\t\tfunctions.\n\t\t\t\t</p>\n\n\t\t\t\t<p role=\"definition\" id=\"bezier\" className=\"p-2 bg-blue-50 border-l-4 border-blue-400 rounded text-sm text-blue-800\">\n\t\t\t\t\tA <strong>Bézier curve</strong>, (Pronounced \\ ˈbe-zē-ˌā \\ <i aria-description=\"English pronunciation\">BEH-zee-ay</i>) is a mathematically described\n\t\t\t\t\tcurve used in computer graphics and animation. The curve is defined by a set of control points with a minimum of two. Web related graphics and\n\t\t\t\t\tanimations use Cubic Béziers, which are curves with four control points P<sub>0</sub>, P<sub>1</sub>, P<sub>2</sub>, and P<sub>3</sub>.\n\t\t\t\t</p>\n\n\t\t\t\t<a\n\t\t\t\t\thref=\"https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function\"\n\t\t\t\t\tid=\"bezImg\"\n\t\t\t\t\taria-label=\"Explanation of Bézier curve in CSS easing functions\"\n\t\t\t\t\ttarget=\"_blank\"\n\t\t\t\t\trel=\"noreferrer\"\n\t\t\t\t\tclassName=\"block w-fit\"\n\t\t\t\t>\n\t\t\t\t\t<svg\n\t\t\t\t\t\twidth=\"200\"\n\t\t\t\t\t\theight=\"160\"\n\t\t\t\t\t\tviewBox=\"0 0 200 160\"\n\t\t\t\t\t\trole=\"img\"\n\t\t\t\t\t\taria-label=\"Cubic Bézier curve showing 4 control points.\"\n\t\t\t\t\t\tclassName=\"border border-gray-400 rounded bg-white\"\n\t\t\t\t\t>\n\t\t\t\t\t\t<path d=\"M 20 130 C 60 10, 140 150, 180 30\" fill=\"none\" stroke=\"#0075ff\" strokeWidth=\"2\" />\n\t\t\t\t\t\t<line x1=\"20\" y1=\"130\" x2=\"60\" y2=\"10\" stroke=\"#888\" strokeDasharray=\"4 3\" />\n\t\t\t\t\t\t<line x1=\"140\" y1=\"150\" x2=\"180\" y2=\"30\" stroke=\"#888\" strokeDasharray=\"4 3\" />\n\t\t\t\t\t\t<circle cx=\"20\" cy=\"130\" r=\"4\" fill=\"#0075ff\" />\n\t\t\t\t\t\t<circle cx=\"60\" cy=\"10\" r=\"4\" fill=\"#888\" />\n\t\t\t\t\t\t<circle cx=\"140\" cy=\"150\" r=\"4\" fill=\"#888\" />\n\t\t\t\t\t\t<circle cx=\"180\" cy=\"30\" r=\"4\" fill=\"#0075ff\" />\n\t\t\t\t\t\t<text x=\"12\" y=\"148\" fontSize=\"12\" fill=\"#202020\">\n\t\t\t\t\t\t\tP0\n\t\t\t\t\t\t</text>\n\t\t\t\t\t\t<text x=\"60\" y=\"24\" fontSize=\"12\" fill=\"#202020\" textAnchor=\"middle\">\n\t\t\t\t\t\t\tP1\n\t\t\t\t\t\t</text>\n\t\t\t\t\t\t<text x=\"140\" y=\"144\" fontSize=\"12\" fill=\"#202020\" textAnchor=\"middle\">\n\t\t\t\t\t\t\tP2\n\t\t\t\t\t\t</text>\n\t\t\t\t\t\t<text x=\"184\" y=\"20\" fontSize=\"12\" fill=\"#202020\" textAnchor=\"end\">\n\t\t\t\t\t\t\tP3\n\t\t\t\t\t\t</text>\n\t\t\t\t\t</svg>\n\t\t\t\t</a>\n\t\t\t</div>\n\t\t</SampleBlock>\n\t</>\n);\n",
1755
1781
  "kind": "sample"
1756
1782
  },
1757
1783
  {
@@ -2906,7 +2932,7 @@
2906
2932
  "kol-table-stateless"
2907
2933
  ],
2908
2934
  "path": "packages/samples/react/src/components/table/stateless-with-settings-menu.tsx",
2909
- "code": "import { KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { SampleDescription } from '../SampleDescription';\n\ntype Data = {\n\tid: string;\n\tname: string;\n\trole: string;\n\temail: string;\n\tactive: string;\n};\nconst DATA: Data[] = [\n\t{ id: 'U1001', name: 'Alice Johnson', role: 'Admin', email: 'alice@example.org', active: 'Yes' },\n\t{ id: 'U1002', name: 'Bob Smith', role: 'Editor', email: 'bob@example.org', active: 'No' },\n\t{ id: 'U1003', name: 'Carol Lee', role: 'Viewer', email: 'carol@example.org', active: 'Yes' },\n\t{ id: 'U1004', name: 'David Kim', role: 'Editor', email: 'david@example.org', active: 'Yes' },\n];\n\nexport const TableStatelessWithSettingsMenu: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows <code>KolTableStateless</code> with the settings menu enabled via\n\t\t\t\t<code>_hasSettingsMenu</code>. Each column demonstrates a different combination of sorting and resizing options.\n\t\t\t</p>\n\t\t\t<p>\n\t\t\t\tEvery column declares an explicit <code>width</code>, so the width fields in the settings menu show the current pixel values instead of starting empty.\n\t\t\t\tThis also prevents a resizable column from collapsing when its width is adjusted from the menu.\n\t\t\t</p>\n\t\t\t<ul>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>ID</strong> keeps a fixed width with <code>resizable: false</code> while still allowing sorting.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Name</strong> represents the default behavior with both sorting and resizing enabled.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Role</strong> disables sorting but keeps <code>resizable: true</code> so users can widen the column if necessary.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>E-Mail</strong> allows sorting but locks its width with <code>resizable: false</code> to keep the layout stable.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Active</strong> is neither sortable nor resizable to emphasise the status indicator.\n\t\t\t\t</li>\n\t\t\t</ul>\n\t\t</SampleDescription>\n\n\t\t<KolTableStateless\n\t\t\t_label=\"Users (stateless with settings menu)\"\n\t\t\tclassName=\"w-full\"\n\t\t\t_hasSettingsMenu={true}\n\t\t\t_headers={{\n\t\t\t\thorizontal: [\n\t\t\t\t\t[\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'id',\n\t\t\t\t\t\t\tlabel: 'ID',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 120,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'name',\n\t\t\t\t\t\t\tlabel: 'Name',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: true,\n\t\t\t\t\t\t\twidth: 200,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'role',\n\t\t\t\t\t\t\tlabel: 'Role',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: false,\n\t\t\t\t\t\t\tresizable: true,\n\t\t\t\t\t\t\twidth: 160,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'email',\n\t\t\t\t\t\t\tlabel: 'E-Mail',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 240,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'active',\n\t\t\t\t\t\t\tlabel: 'Active',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: false,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 120,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t],\n\t\t\t}}\n\t\t\t_data={DATA}\n\t\t\t_on={{\n\t\t\t\tonSort: (_e, payload) => console.log('sort', payload),\n\t\t\t\tonSelectionChange: (_e, value) => console.log('selection', value),\n\t\t\t}}\n\t\t/>\n\t</>\n);\n",
2935
+ "code": "import { KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { SampleDescription } from '../SampleDescription';\n\ntype Data = {\n\tid: string;\n\tname: string;\n\trole: string;\n\temail: string;\n\tactive: string;\n};\nconst DATA: Data[] = [\n\t{ id: 'U1001', name: 'Alice Johnson', role: 'Admin', email: 'alice@example.org', active: 'Yes' },\n\t{ id: 'U1002', name: 'Bob Smith', role: 'Editor', email: 'bob@example.org', active: 'No' },\n\t{ id: 'U1003', name: 'Carol Lee', role: 'Viewer', email: 'carol@example.org', active: 'Yes' },\n\t{ id: 'U1004', name: 'David Kim', role: 'Editor', email: 'david@example.org', active: 'Yes' },\n];\n\nexport const TableStatelessWithSettingsMenu: FC = () => (\n\t<>\n\t\t<SampleDescription>\n\t\t\t<p>\n\t\t\t\tThis sample shows <code>KolTableStateless</code> with the settings menu enabled via\n\t\t\t\t<code>_hasSettingsMenu</code>. Each column demonstrates a different combination of sorting and resizing options.\n\t\t\t</p>\n\t\t\t<p>\n\t\t\t\tEvery column declares an explicit <code>width</code>, so the width fields in the settings menu show the current pixel values instead of starting empty.\n\t\t\t\tThis also prevents a resizable column from collapsing when its width is adjusted from the menu.\n\t\t\t</p>\n\t\t\t<ul>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>ID</strong> keeps a fixed width with <code>resizable: false</code> while still allowing sorting.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Name</strong> represents the default behavior with both sorting and resizing enabled.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Role</strong> disables sorting but keeps <code>resizable: true</code> so users can widen the column if necessary.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>E-Mail</strong> allows sorting but locks its width with <code>resizable: false</code> to keep the layout stable.\n\t\t\t\t</li>\n\t\t\t\t<li>\n\t\t\t\t\t<strong>Active</strong> is neither sortable nor resizable to emphasise the status indicator.\n\t\t\t\t</li>\n\t\t\t</ul>\n\t\t</SampleDescription>\n\n\t\t<KolTableStateless\n\t\t\t_label=\"Users (stateless with settings menu)\"\n\t\t\tclassName=\"w-full\"\n\t\t\t_hasSettingsMenu={true}\n\t\t\t_headers={{\n\t\t\t\thorizontal: [\n\t\t\t\t\t[\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'id',\n\t\t\t\t\t\t\tlabel: 'ID',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 120,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'name',\n\t\t\t\t\t\t\tlabel: 'Name',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: true,\n\t\t\t\t\t\t\twidth: 200,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'role',\n\t\t\t\t\t\t\tlabel: 'Role',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: false,\n\t\t\t\t\t\t\tresizable: true,\n\t\t\t\t\t\t\twidth: 160,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'email',\n\t\t\t\t\t\t\tlabel: 'E-Mail',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: true,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 240,\n\t\t\t\t\t\t},\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\tkey: 'active',\n\t\t\t\t\t\t\tlabel: 'Active',\n\t\t\t\t\t\t\ttextAlign: 'center',\n\t\t\t\t\t\t\tsortDirection: 'NOS',\n\t\t\t\t\t\t\tsortable: false,\n\t\t\t\t\t\t\tresizable: false,\n\t\t\t\t\t\t\twidth: 120,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t],\n\t\t\t}}\n\t\t\t_data={DATA}\n\t\t\t_on={{\n\t\t\t\tonSort: (_e, payload) => console.log('sort', payload),\n\t\t\t\tonSelectionChange: (_e, value) => console.log('selection', value),\n\t\t\t\tonChangeHeaderCells: (_e, value) => console.log('header settings changed', value),\n\t\t\t}}\n\t\t/>\n\t</>\n);\n",
2910
2936
  "kind": "sample"
2911
2937
  },
2912
2938
  {
@@ -3398,6 +3424,40 @@
3398
3424
  "code": "import type { FC } from 'react';\nimport React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';\n\nimport {\n\tKolButton,\n\tKolButtonLink,\n\tKolCard,\n\tKolCombobox,\n\tKolInputCheckbox,\n\tKolInputColor,\n\tKolInputDate,\n\tKolInputEmail,\n\tKolInputFile,\n\tKolInputNumber,\n\tKolInputPassword,\n\tKolInputRadio,\n\tKolInputRange,\n\tKolInputText,\n\tKolSelect,\n\tKolSingleSelect,\n\tKolTextarea,\n} from '@public-ui/react-v19';\n\nimport { SampleDescription } from '../components/SampleDescription';\nimport { COUNTRY_SUGGESTIONS } from '../shares/country';\n\nimport type { W3CInputValue } from '@public-ui/components';\nimport type { HTMLStencilElement } from '@stencil/core/internal';\n\nconst EventTargetContext = createContext<EventTarget | undefined>(undefined);\nconst EventLoggerActiveContext = createContext<boolean>(false);\n\ntype Props = {\n\tInputComponent: React.ComponentType<any>;\n\tinputProps: { [key: string]: any };\n\tformatter?: (value: any) => string;\n\ttestId?: string;\n};\nconst Scenario = (props: Props) => {\n\tconst ref = useRef<HTMLStencilElement & { getValue: () => Promise<any> }>(null);\n\tconst [displayValue, setDisplayValue] = useState<unknown>(undefined);\n\tconst [modelValue, setModelValue] = useState<unknown>(props.inputProps._value);\n\tconst formatter = props.formatter || JSON.stringify;\n\tconst eventTarget = useContext(EventTargetContext);\n\tconst eventLoggerActive = useContext(EventLoggerActiveContext);\n\n\tconst handleButtonClick = useCallback(async () => {\n\t\tconst value = await ref.current?.getValue();\n\t\tsetDisplayValue(value);\n\t}, []);\n\n\tuseEffect(() => {\n\t\tconst handleRunAll = () => {\n\t\t\tvoid handleButtonClick();\n\t\t};\n\t\teventTarget?.addEventListener('runAll', handleRunAll);\n\n\t\treturn () => {\n\t\t\teventTarget?.removeEventListener('runAll', handleRunAll);\n\t\t};\n\t}, [eventTarget, handleButtonClick]);\n\n\tconst eventListeners = Object.fromEntries(\n\t\t['onInput', 'onChange', 'onBlur', 'onClick', 'onFocus', 'onMouseDown'].map((eventName) => [\n\t\t\teventName,\n\t\t\t(event: Event, value: W3CInputValue) => {\n\t\t\t\tif (eventLoggerActive) {\n\t\t\t\t\tconsole.log(props.inputProps._label, eventName, value, event);\n\t\t\t\t}\n\t\t\t\tif (eventName === 'onInput') {\n\t\t\t\t\tsetModelValue(value);\n\t\t\t\t}\n\t\t\t},\n\t\t]),\n\t);\n\n\treturn (\n\t\t<>\n\t\t\t<div className=\"grid grid-cols-3 items-end gap-4\" data-testid={props.testId}>\n\t\t\t\t<props.InputComponent ref={ref} _on={eventListeners} {...props.inputProps} _value={modelValue} />\n\t\t\t\t<KolButton\n\t\t\t\t\t_label=\"getValue()\"\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonClick: () => {\n\t\t\t\t\t\t\tvoid handleButtonClick();\n\t\t\t\t\t\t},\n\t\t\t\t\t}}\n\t\t\t\t></KolButton>\n\t\t\t\t<pre className=\"text-base\">{formatter(displayValue)}</pre>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n\nexport const InputsGetValue: FC = () => {\n\tconst eventTarget = useMemo(() => new EventTarget(), []);\n\tconst [eventLoggerActive, setEventLoggerActive] = useState<boolean>(true);\n\n\treturn (\n\t\t<>\n\t\t\t<EventTargetContext.Provider value={eventTarget}>\n\t\t\t\t<EventLoggerActiveContext.Provider value={eventLoggerActive}>\n\t\t\t\t\t<SampleDescription>\n\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\tThis sample shows how the input components <code>getValue()</code> method works. It&apos;s called when clicking the &quot;getValue()&quot; button\n\t\t\t\t\t\t\tand prints the current value right next to itself.\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</SampleDescription>\n\n\t\t\t\t\t<section className=\"w-full flex flex-col\">\n\t\t\t\t\t\t<KolCard _label=\"Sample options\" className=\"block ha mb-8\">\n\t\t\t\t\t\t\t<KolInputCheckbox\n\t\t\t\t\t\t\t\t_label=\"Log events to console\"\n\t\t\t\t\t\t\t\t_value={true}\n\t\t\t\t\t\t\t\t_checked={eventLoggerActive}\n\t\t\t\t\t\t\t\t_on={{ onChange: (_, active) => setEventLoggerActive(active as boolean) }}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t</KolCard>\n\n\t\t\t\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputText\" InputComponent={KolInputText} inputProps={{ _label: 'InputText' }} />\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-inputCheckboxString\"\n\t\t\t\t\t\t\t\tInputComponent={KolInputCheckbox}\n\t\t\t\t\t\t\t\tinputProps={{ _label: 'KolInputCheckbox (value)', _value: 'Checkbox True Value' }}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputCheckboxBoolean\" InputComponent={KolInputCheckbox} inputProps={{ _label: 'KolInputCheckbox (boolean)' }} />\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputColor\" InputComponent={KolInputColor} inputProps={{ _label: 'KolInputColor' }} />\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputDate\" InputComponent={KolInputDate} inputProps={{ _label: 'KolInputDate' }} />\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputEmail\" InputComponent={KolInputEmail} inputProps={{ _label: 'KolInputEmail' }} />\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-inputFile\"\n\t\t\t\t\t\t\t\tInputComponent={KolInputFile}\n\t\t\t\t\t\t\t\tinputProps={{ _label: 'KolInputFile' }}\n\t\t\t\t\t\t\t\tformatter={(value) =>\n\t\t\t\t\t\t\t\t\tvalue instanceof FileList\n\t\t\t\t\t\t\t\t\t\t? `FileList{${Array.from(value)\n\t\t\t\t\t\t\t\t\t\t\t\t.map((file: File) => file.name)\n\t\t\t\t\t\t\t\t\t\t\t\t.join(', ')}}`\n\t\t\t\t\t\t\t\t\t\t: JSON.stringify(value)\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputNumber\" InputComponent={KolInputNumber} inputProps={{ _label: 'KolInputNumber' }} />\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputPassword\" InputComponent={KolInputPassword} inputProps={{ _label: 'KolInputPassword' }} />\n\t\t\t\t\t\t\t<Scenario testId=\"scenario-inputRange\" InputComponent={KolInputRange} inputProps={{ _label: 'KolInputRange' }} />\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-inputRadio\"\n\t\t\t\t\t\t\t\tInputComponent={KolInputRadio}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolInputRadio',\n\t\t\t\t\t\t\t\t\t_orientation: 'horizontal',\n\t\t\t\t\t\t\t\t\t_options: [\n\t\t\t\t\t\t\t\t\t\t{ label: 'New York', value: 'New York' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rio de Janeiro', value: 'Rio de Janeiro' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rosenheim', value: 'Rosenheim' },\n\t\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t\t\t_value: 'New York',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-select\"\n\t\t\t\t\t\t\t\tInputComponent={KolSelect}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolSelect',\n\t\t\t\t\t\t\t\t\t_options: [\n\t\t\t\t\t\t\t\t\t\t{ label: 'New York', value: 'New York' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rio de Janeiro', value: 'Rio de Janeiro' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rosenheim', value: 'Rosenheim' },\n\t\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-singleSelect\"\n\t\t\t\t\t\t\t\tInputComponent={KolSingleSelect}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolSingleSelect',\n\t\t\t\t\t\t\t\t\t_options: [\n\t\t\t\t\t\t\t\t\t\t{ label: 'New York', value: 'New York' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rio de Janeiro', value: 'Rio de Janeiro' },\n\t\t\t\t\t\t\t\t\t\t{ label: 'Rosenheim', value: 'Rosenheim' },\n\t\t\t\t\t\t\t\t\t],\n\t\t\t\t\t\t\t\t\t_value: 'Rosenheim',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-combobox\"\n\t\t\t\t\t\t\t\tInputComponent={KolCombobox}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolCombobox',\n\t\t\t\t\t\t\t\t\t_suggestions: COUNTRY_SUGGESTIONS,\n\t\t\t\t\t\t\t\t\t_value: 'Deutschland',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-textarea\"\n\t\t\t\t\t\t\t\tInputComponent={KolTextarea}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolTextarea',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-button\"\n\t\t\t\t\t\t\t\tInputComponent={KolButton}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolButton',\n\t\t\t\t\t\t\t\t\t_variant: 'ghost',\n\t\t\t\t\t\t\t\t\t_value: 'KolButton value',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t<Scenario\n\t\t\t\t\t\t\t\ttestId=\"scenario-buttonLink\"\n\t\t\t\t\t\t\t\tInputComponent={KolButtonLink}\n\t\t\t\t\t\t\t\tinputProps={{\n\t\t\t\t\t\t\t\t\t_label: 'KolButtonLink',\n\t\t\t\t\t\t\t\t\t_value: 'KolButtonLink value',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t/>\n\n\t\t\t\t\t\t\t<div className=\"grid grid-cols-3 gap-4\">\n\t\t\t\t\t\t\t\t<div></div>\n\t\t\t\t\t\t\t\t<KolButton\n\t\t\t\t\t\t\t\t\t_label=\"Run all\"\n\t\t\t\t\t\t\t\t\t_variant=\"primary\"\n\t\t\t\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\t\t\t\tonClick: () => {\n\t\t\t\t\t\t\t\t\t\t\teventTarget.dispatchEvent(new Event('runAll'));\n\t\t\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t\t></KolButton>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t</section>\n\t\t\t\t</EventLoggerActiveContext.Provider>\n\t\t\t</EventTargetContext.Provider>\n\t\t</>\n\t);\n};\n",
3399
3425
  "kind": "scenario"
3400
3426
  },
3427
+ {
3428
+ "id": "scenario/scenarios/label-lang",
3429
+ "group": "scenarios",
3430
+ "name": "label-lang",
3431
+ "description": "Label can use additional language attributes for screenreaders.",
3432
+ "tags": [
3433
+ "kol-accordion",
3434
+ "kol-alert",
3435
+ "kol-badge",
3436
+ "kol-breadcrumb",
3437
+ "kol-button",
3438
+ "kol-button-link",
3439
+ "kol-card",
3440
+ "kol-details",
3441
+ "kol-heading",
3442
+ "kol-input-checkbox",
3443
+ "kol-input-text",
3444
+ "kol-link",
3445
+ "kol-link-button",
3446
+ "kol-meter",
3447
+ "kol-nav",
3448
+ "kol-popover-button",
3449
+ "kol-progress",
3450
+ "kol-quote",
3451
+ "kol-table-stateful",
3452
+ "kol-tabs",
3453
+ "kol-toolbar",
3454
+ "kol-tree",
3455
+ "kol-tree-item"
3456
+ ],
3457
+ "path": "packages/samples/react/src/scenarios/label-lang.tsx",
3458
+ "code": "import React from 'react';\n\nimport {\n\tKolAccordion,\n\tKolAlert,\n\tKolBadge,\n\tKolBreadcrumb,\n\tKolButton,\n\tKolButtonLink,\n\tKolCard,\n\tKolDetails,\n\tKolHeading,\n\tKolInputCheckbox,\n\tKolInputText,\n\tKolLink,\n\tKolLinkButton,\n\tKolMeter,\n\tKolNav,\n\tKolPopoverButton,\n\tKolProgress,\n\tKolQuote,\n\tKolTableStateful,\n\tKolTabs,\n\tKolToolbar,\n\tKolTree,\n\tKolTreeItem,\n} from '@public-ui/react-v19';\nimport { SampleBlock } from '../components/SampleBlock';\nimport { SampleDescription } from '../components/SampleDescription';\n\nimport type { KoliBriTableHeaders } from '@public-ui/components';\nimport type { FC } from 'react';\n\nexport const LabelLang: FC = () => {\n\tconst defaultLabel = (component: string) => [{ text: component }, { text: 'partly english', lang: 'en' }, { text: ' Label', lang: 'de' }];\n\n\tconst navLinks = [\n\t\t{\n\t\t\t_label: defaultLabel('Link '),\n\t\t\t_href: '#/',\n\t\t},\n\t\t{\n\t\t\t_label: defaultLabel('Link '),\n\t\t\t_href: '#/',\n\t\t},\n\t];\n\n\tconst tabs = [\n\t\t{\n\t\t\t_label: defaultLabel('Tab '),\n\t\t},\n\t\t{\n\t\t\t_label: 'Second Tab',\n\t\t},\n\t];\n\n\tconst HEADER: KoliBriTableHeaders = {\n\t\thorizontal: [[{ label: 'ID', key: 'id', width: 160 }]],\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>Label can use additional language attributes for screenreaders.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-4\">\n\t\t\t\t<SampleBlock id=\"label-lang-accordion\">\n\t\t\t\t\t<KolAccordion _label={defaultLabel('Accordion ')}>\n\t\t\t\t\t\t<p>Contents Accordion</p>\n\t\t\t\t\t</KolAccordion>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-alert\">\n\t\t\t\t\t<KolAlert _label={defaultLabel('Alert ')}>This is the text of the alert.</KolAlert>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-badge\">\n\t\t\t\t\t<KolBadge _label={defaultLabel('Badge ')}></KolBadge>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-breadcrumb\">\n\t\t\t\t\t<KolBreadcrumb _label=\"Breadcrumb\" _links={navLinks} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-button\">\n\t\t\t\t\t<KolButton _label={defaultLabel('Button ')} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-button-link\">\n\t\t\t\t\t<KolButtonLink _label={defaultLabel('ButtonLink ')} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-card\">\n\t\t\t\t\t<KolCard _label={defaultLabel('Card ')}>Inhaltsbereich</KolCard>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-details\">\n\t\t\t\t\t<KolDetails _label={defaultLabel('Details ')}>\n\t\t\t\t\t\t<p>Contents Details</p>\n\t\t\t\t\t</KolDetails>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-heading\">\n\t\t\t\t\t<KolHeading _label={defaultLabel('Heading ')} _level={1} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-checkbox\">\n\t\t\t\t\t<KolInputCheckbox _label={defaultLabel('Checkbox')} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-input\">\n\t\t\t\t\t<KolInputText _label={defaultLabel('Input ')} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-link\">\n\t\t\t\t\t<KolLink _label={defaultLabel('Link ')} _href=\"\" />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-link-button\">\n\t\t\t\t\t<KolLinkButton _label={defaultLabel('LinkButton ')} _href=\"\" />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-meter\">\n\t\t\t\t\t<KolMeter _label={defaultLabel('Meter ')} _max={1024} _min={0} _unit=\"MB\" _value={512} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-nav\">\n\t\t\t\t\t<KolNav _label=\"Navi\" _links={navLinks} />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-popover\">\n\t\t\t\t\t<KolPopoverButton _label={defaultLabel('Popover ')}>Text</KolPopoverButton>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-progress\">\n\t\t\t\t\t<KolProgress _label={defaultLabel('Progress ')} _max={100} _value={45} _variant=\"bar\" />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-quote\">\n\t\t\t\t\t<KolQuote _href=\"https://public-ui.github.io/docs\" _label={defaultLabel('Quote ')} _quote=\"Quote.\" _variant=\"inline\" />\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-table\">\n\t\t\t\t\t<KolTableStateful _label={defaultLabel('Table ')} _data={[]} _headers={HEADER}></KolTableStateful>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-tabs\">\n\t\t\t\t\t<KolTabs _tabs={tabs} _label=\"Regular tabs\"></KolTabs>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-toolbar\">\n\t\t\t\t\t<KolToolbar\n\t\t\t\t\t\t_label=\"Toolbar\"\n\t\t\t\t\t\t_items={[\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\ttype: 'button',\n\t\t\t\t\t\t\t\t_label: defaultLabel('Button '),\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t{\n\t\t\t\t\t\t\t\ttype: 'link',\n\t\t\t\t\t\t\t\t_label: defaultLabel('Link '),\n\t\t\t\t\t\t\t\t_href: '#',\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t]}\n\t\t\t\t\t></KolToolbar>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"label-lang-tree\">\n\t\t\t\t\t<KolTree _label=\"Tree\">\n\t\t\t\t\t\t<KolTreeItem _label={defaultLabel('TreeItem ')} _href=\"#/\" />\n\t\t\t\t\t</KolTree>\n\t\t\t\t</SampleBlock>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
3459
+ "kind": "scenario"
3460
+ },
3401
3461
  {
3402
3462
  "id": "scenario/scenarios/performance-test",
3403
3463
  "group": "scenarios",
@@ -3503,34 +3563,6 @@
3503
3563
  "code": "import {\n\tKolButton,\n\tKolCombobox,\n\tKolInputColor,\n\tKolInputDate,\n\tKolInputEmail,\n\tKolInputFile,\n\tKolInputNumber,\n\tKolInputPassword,\n\tKolInputRange,\n\tKolInputText,\n\tKolLinkButton,\n\tKolSelect,\n\tKolSingleSelect,\n\tKolTextarea,\n} from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\nimport { useAlert } from '../hooks/useAlert';\n\nexport const SameHeightOfAllInteractiveElements: FC = () => {\n\tconst { dummyClickEventHandler } = useAlert();\n\n\tconst dummyEventHandler = {\n\t\tonClick: dummyClickEventHandler,\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tAll interactive elements, such as buttons and input fields, should have the same height to ensure a consistent and visually balanced user interface.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\t\t\t<div className=\"w-full flex flex-wrap gap-4\">\n\t\t\t\t<KolButton _icons=\"kolicon-house\" _label=\"Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolButton _hideLabel _icons=\"kolicon-house\" _label=\"Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolLinkButton _href=\"#\" _icons=\"kolicon-house\" _label=\"Link-Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolLinkButton _hideLabel _href=\"#\" _icons=\"kolicon-house\" _label=\"Link-Button\" _on={dummyEventHandler} />\n\t\t\t\t<KolCombobox _hideLabel _icons=\"kolicon-house\" _label=\"Combobox\" _suggestions={[]} />\n\t\t\t\t<KolInputColor\n\t\t\t\t\t_hideLabel\n\t\t\t\t\t_icons={{\n\t\t\t\t\t\tleft: 'kolicon-house',\n\t\t\t\t\t}}\n\t\t\t\t\t_label=\"Input-Color\"\n\t\t\t\t/>\n\t\t\t\t<KolInputFile _hideLabel _icons=\"kolicon-house\" _label=\"Input-File\" />\n\t\t\t\t<KolInputDate _hideLabel _icons=\"kolicon-house\" _label=\"Input-Date\" />\n\t\t\t\t<KolInputEmail _hideLabel _icons=\"kolicon-house\" _label=\"Input-Email\" />\n\t\t\t\t<KolInputNumber _hideLabel _icons=\"kolicon-house\" _label=\"Input-Number\" />\n\t\t\t\t<KolInputPassword _hideLabel _icons=\"kolicon-house\" _label=\"Input-Password\" />\n\t\t\t\t<KolInputRange _hideLabel _icons=\"kolicon-house\" _label=\"Input-Range\" />\n\t\t\t\t<KolInputText _hideLabel _icons=\"kolicon-house\" _label=\"Input-Text\" />\n\t\t\t\t<KolSelect _hideLabel _icons=\"kolicon-house\" _label=\"Select\" _options={[]} />\n\t\t\t\t<KolSingleSelect _hideLabel _icons=\"kolicon-house\" _label=\"Single Select\" _options={[]} />\n\t\t\t\t<KolTextarea _hideLabel _icons=\"kolicon-house\" _label=\"Textarea\" />\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
3504
3564
  "kind": "scenario"
3505
3565
  },
3506
- {
3507
- "id": "scenario/scenarios/sample-form-with-validation",
3508
- "group": "scenarios",
3509
- "name": "sample-form-with-validation",
3510
- "description": "This example shows validation with react-hook-form, Zod, and an error list.",
3511
- "tags": [
3512
- "kol-alert",
3513
- "kol-button",
3514
- "kol-combobox-controller",
3515
- "kol-heading",
3516
- "kol-input-checkbox-controller",
3517
- "kol-input-color-controller",
3518
- "kol-input-date-controller",
3519
- "kol-input-email-controller",
3520
- "kol-input-number-controller",
3521
- "kol-input-password-controller",
3522
- "kol-input-radio-controller",
3523
- "kol-input-range-controller",
3524
- "kol-input-text-controller",
3525
- "kol-link",
3526
- "kol-select-controller",
3527
- "kol-single-select-controller",
3528
- "kol-textarea-controller"
3529
- ],
3530
- "path": "packages/samples/react/src/scenarios/sample-form-with-validation.tsx",
3531
- "code": "import { zodResolver } from '@hookform/resolvers/zod';\nimport {\n\tKolComboboxController,\n\tKolInputCheckboxController,\n\tKolInputColorController,\n\tKolInputDateController,\n\tKolInputEmailController,\n\tKolInputNumberController,\n\tKolInputPasswordController,\n\tKolInputRadioController,\n\tKolInputRangeController,\n\tKolInputTextController,\n\tKolSelectController,\n\tKolSingleSelectController,\n\tKolTextareaController,\n} from '@public-ui/react-hook-form-adapter';\nimport { KolAlert, KolButton, KolHeading, KolLink } from '@public-ui/react-v19';\nimport React from 'react';\nimport type { FieldError } from 'react-hook-form';\nimport { useForm } from 'react-hook-form';\nimport { z } from 'zod';\n\nimport { SampleDescription } from '../components/SampleDescription';\nimport { useAlert } from '../hooks/useAlert';\nimport { COUNTRY_SUGGESTIONS } from '../shares/country';\n\nconst formSchema = z.object({\n\tdate: z.preprocess(\n\t\t(val) => (typeof val === 'string' || val instanceof Date ? new Date(val) : undefined),\n\t\tz.date({ message: 'Date is required' }).refine((d) => !isNaN(d.getTime()), { message: 'Invalid date' }),\n\t),\n\n\ttext: z.string({ message: 'Please enter text.' }).min(10, 'Text must be at least 10 characters long.'),\n\temail: z.string({ message: 'Please enter your email.' }).min(1, 'Please enter your email.').email('Invalid email address.'),\n\tpassword: z\n\t\t.string({ message: 'Please enter a password.' })\n\t\t.min(8, 'Password must be at least 8 characters.')\n\t\t.regex(/[A-Z]/, 'Password must include at least one uppercase letter.')\n\t\t.regex(/[0-9]/, 'Password must include at least one number.'),\n\trange: z.number({ message: 'Please select a range.' }).min(30, 'Minimum value is 30.'),\n\tnumber: z.number({ message: 'Please enter a number.' }).min(1, 'Minimum is 1.').max(10, 'Maximum is 10.'),\n\tcheckbox: z.boolean().refine((val: boolean) => val === true, {\n\t\tmessage: 'You must accept the terms and conditions.',\n\t}),\n\n\tradio: z.string({ message: 'Please select a gender.' }).min(1, 'Please select a gender.'),\n\tcolor: z.string({ message: 'Please select a color.' }).min(1, 'Please select a color.'),\n\tselect: z.string({ message: 'Please select a value.' }).min(1, 'Please select a value.'),\n\tsingleSelect: z.string({ message: 'Please select a single option.' }).min(1, 'Please select a single option.'),\n\tcombobox: z.string({ message: 'Please select a country.' }).min(1, 'Please select a country.'),\n\ttextarea: z.string({ message: 'Please enter a message.' }).min(1, 'Please enter a message.'),\n});\n\nexport const SampleFormWithValidation: React.FC = () => {\n\tconst { dummyClickEventHandler } = useAlert();\n\tconst {\n\t\thandleSubmit,\n\t\tformState: { errors },\n\t\treset,\n\t\tcontrol,\n\t} = useForm({\n\t\tmode: 'onBlur',\n\t\treValidateMode: 'onChange',\n\t\tresolver: zodResolver(formSchema),\n\t\tdefaultValues: {\n\t\t\trange: 30,\n\t\t\tnumber: 5,\n\t\t},\n\t});\n\n\tconst onReset = () => {\n\t\treset(undefined, {\n\t\t\tkeepErrors: false,\n\t\t\tkeepTouched: false,\n\t\t\tkeepDirty: false,\n\t\t});\n\t};\n\n\tconst allErrors = Object.entries(errors)\n\t\t.map(([key, value]) => [key, (value as FieldError).message] as const)\n\t\t.filter(([, msg]) => Boolean(msg));\n\n\treturn (\n\t\t<section className=\"w-full max-w-3xl mx-auto p-6\">\n\t\t\t<KolHeading _level={2} _label=\"Sample Form with Validation (Zod)\" />\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis example shows validation with <code>react-hook-form</code>, <code>Zod</code>, and an error list.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t{allErrors.length > 0 && (\n\t\t\t\t<KolAlert _type=\"error\" _label=\"Please fix the following:\" _alert _variant=\"card\">\n\t\t\t\t\t<ul className=\"list-disc pl-5\">\n\t\t\t\t\t\t{allErrors.map(([key, msg], i) => (\n\t\t\t\t\t\t\t<li key={i}>\n\t\t\t\t\t\t\t\t<KolLink\n\t\t\t\t\t\t\t\t\t_label={msg}\n\t\t\t\t\t\t\t\t\t_href={`#field-${key}`}\n\t\t\t\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\t\t\t\tonClick: (e: Event) => {\n\t\t\t\t\t\t\t\t\t\t\te.preventDefault();\n\t\t\t\t\t\t\t\t\t\t\tconst input = document.getElementById(`field-${key}`);\n\t\t\t\t\t\t\t\t\t\t\tinput?.focus();\n\t\t\t\t\t\t\t\t\t\t},\n\t\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t\t/>\n\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t))}\n\t\t\t\t\t</ul>\n\t\t\t\t</KolAlert>\n\t\t\t)}\n\n\t\t\t<form onSubmit={handleSubmit(dummyClickEventHandler)} noValidate className=\"grid gap-4 mt-6\">\n\t\t\t\t<KolInputDateController control={control as any} name=\"date\" _label=\"Date\" />\n\t\t\t\t<KolInputTextController control={control as any} name=\"text\" _label=\"Text (≥ 10 chars)\" />\n\t\t\t\t<KolInputEmailController control={control as any} name=\"email\" _label=\"Email\" />\n\t\t\t\t<KolInputPasswordController control={control as any} name=\"password\" _label=\"Password\" />\n\t\t\t\t<KolInputRangeController control={control as any} name=\"range\" _label=\"Range (≥ 30)\" _min={0} _max={100} />\n\t\t\t\t<KolInputNumberController control={control as any} name=\"number\" _label=\"Number (1 – 10)\" />\n\t\t\t\t<KolInputCheckboxController control={control as any} name=\"checkbox\" _label=\"Accept terms\" />\n\t\t\t\t<KolInputRadioController\n\t\t\t\t\tcontrol={control as any}\n\t\t\t\t\tname=\"radio\"\n\t\t\t\t\t_label=\"Gender\"\n\t\t\t\t\t_options={[\n\t\t\t\t\t\t{ label: 'Female', value: 'f' },\n\t\t\t\t\t\t{ label: 'Male', value: 'm' },\n\t\t\t\t\t]}\n\t\t\t\t/>\n\t\t\t\t<KolInputColorController control={control as any} name=\"color\" _label=\"Favorite Color\" />\n\t\t\t\t<KolSelectController\n\t\t\t\t\tcontrol={control as any}\n\t\t\t\t\tname=\"select\"\n\t\t\t\t\t_label=\"Select\"\n\t\t\t\t\t_options={[\n\t\t\t\t\t\t{ label: 'Option A', value: 'A' },\n\t\t\t\t\t\t{ label: 'Option B', value: 'B' },\n\t\t\t\t\t]}\n\t\t\t\t/>\n\t\t\t\t<KolSingleSelectController\n\t\t\t\t\tcontrol={control as any}\n\t\t\t\t\tname=\"singleSelect\"\n\t\t\t\t\t_label=\"Single Select\"\n\t\t\t\t\t_options={[\n\t\t\t\t\t\t{ label: 'Option A', value: 'A' },\n\t\t\t\t\t\t{ label: 'Option B', value: 'B' },\n\t\t\t\t\t]}\n\t\t\t\t/>\n\t\t\t\t<KolComboboxController control={control as any} name=\"combobox\" _label=\"Country\" _suggestions={COUNTRY_SUGGESTIONS} />\n\t\t\t\t<KolTextareaController control={control as any} name=\"textarea\" _label=\"Message\" _rows={4} />\n\n\t\t\t\t<div className=\"flex gap-4 mt-4\">\n\t\t\t\t\t<KolButton _label=\"Submit\" _type=\"submit\" _variant=\"primary\" />\n\t\t\t\t\t<KolButton _label=\"Reset\" _type=\"reset\" onClick={onReset} />\n\t\t\t\t</div>\n\t\t\t</form>\n\t\t</section>\n\t);\n};\n",
3532
- "kind": "scenario"
3533
- },
3534
3566
  {
3535
3567
  "id": "scenario/scenarios/skeleton",
3536
3568
  "group": "scenarios",
@@ -3612,22 +3644,13 @@
3612
3644
  "code": "import type { FC } from 'react';\nimport React, { useEffect, useRef } from 'react';\n\nimport { KolButton, KolCombobox, KolDialog, KolInputNumber, KolPopoverButton } from '@public-ui/react-v19';\nimport { useSearchParams } from 'react-router';\nimport { SampleDescription } from '../components/SampleDescription';\n\nexport const ZIndexScenario: FC = () => {\n\tconst [searchParams] = useSearchParams();\n\n\tconst showDialog = searchParams.get('show-dialog') as string;\n\n\tconst cardRef = useRef<HTMLKolDialogElement>(null);\n\n\tconst onOpenCardDialog = {\n\t\tonClick: () => cardRef.current?.openModal(),\n\t};\n\n\tuseEffect(() => {\n\t\tif (showDialog === 'true') {\n\t\t\tcardRef.current?.openModal();\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 the combination of a few components overlaying content. Dialog, Popover, Tooltip</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid gap-8\">\n\t\t\t\t<div>\n\t\t\t\t\t<KolButton _label=\"Open card dialog\" _on={onOpenCardDialog} />\n\t\t\t\t\t<KolDialog ref={cardRef} _label=\"Card dialog\" _variant=\"card\" _width=\"30%\">\n\t\t\t\t\t\t<KolPopoverButton _label=\"Help\" _icons=\"kolicon-alert-info\" _popoverAlign=\"right\" _tooltipAlign=\"bottom\" _hideLabel>\n\t\t\t\t\t\t\t<div className=\"w-sm p-2 border border-solid border-gray\">\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t<u>Lorem ipsum dolor sit amet</u>, consectetur adipisicing elit. Aspernatur aut dolore dolores itaque praesentium reprehenderit sed\n\t\t\t\t\t\t\t\t\tvoluptatum! Exercitationem ipsa magni maiores modi, placeat quas quos reprehenderit rerum sit veniam vitae.\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<KolButton _hideLabel _icons=\"kolicon-check\" _label=\"OK\" _variant=\"primary\" />\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</KolPopoverButton>\n\t\t\t\t\t\t<KolCombobox _label=\"With string array in html\" _suggestions=\"['Herr','Frau','Firma']\" _value=\"Herr\" _hideLabel />\n\t\t\t\t\t\t<KolInputNumber _label=\"Amount\" />\n\t\t\t\t\t</KolDialog>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
3613
3645
  "kind": "scenario"
3614
3646
  },
3615
- {
3616
- "id": "spec/_skeleton",
3617
- "group": "spec",
3618
- "name": "_skeleton",
3619
- "description": "Wenn Props über PropsConfigShape + ApiFromConfig in api.tsx definiert werden, erzwingt TypeScript nur einen Teil des erforderlichen Boilerplates in der Web-Component-Klasse.",
3620
- "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/_skeleton.md",
3621
- "code": "# TODO: Props-Pattern-Enforcement\n\n## Problem\n\nWenn Props über `PropsConfigShape` + `ApiFromConfig` in `api.tsx` definiert werden, erzwingt TypeScript nur einen Teil des erforderlichen Boilerplates in der Web-Component-Klasse.\n\nDas **Prop-Dreieck** besteht aus drei Teilen — nur einer davon ist type-erzwungen:\n\n| Teil | Type-erzwungen? | Was passiert bei Fehlen |\n| ----------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |\n| Felddeklaration `_name!: string` | **Ja** — via `ComponentProps<T>` in `WebComponentInterface` | compile error |\n| `@Prop()` Decorator | **Nein** | kein Attribut-Binding, silent runtime bug |\n| `@Watch('_name')` Decorator | **Nein** (`watchName()` Methode wird erzwungen, aber nicht der Decorator) | Stencil ruft Methode nie auf, silent runtime bug |\n| Forwarding in `componentWillLoad()` | **Nein** | Prop-Wert kommt nie in der WC an |\n\n## Aktueller Stand\n\n`implements WebComponentInterface<SkeletonApi>` ist korrekt und schon vorhanden — es deckt alles ab, was TypeScript abdecken _kann_. Die Lücke ist Stencil-spezifisch: Stencil-Decorators sind reine Metadaten und für das TypeScript-Typsystem unsichtbar.\n\n## Lösungsoptionen\n\n### Option A: Custom ESLint-Regel (empfohlen, kurzfristig)\n\nEine AST-basierte Regel mit `@typescript-eslint`, die prüft:\n\n> Jedes Feld einer Klasse, die `implements WebComponentInterface<...>` trägt und dem Muster `_${name}` entspricht, muss `@Prop()` und ein `@Watch('_${name}')` besitzen.\n\n- Machbar ohne Änderungen am Typsystem\n- Greift in CI/CD und im Editor\n- Schließt die Lücke für bestehende und neue Komponenten\n\n### Option B: Code-Generator für Prop-Dreieck-Boilerplate (empfohlen, langfristig)\n\nEin Script/Tool, das aus `propsConfig` automatisch den WebComponent-Boilerplate erzeugt:\n\n```ts\n// aus: skeletonPropsConfig.required = [nameProp]\n// wird generiert:\n\n@Prop() public _name!: string;\n\n@Watch('_name')\nwatchName(value?: string): void {\n nameProp.apply(value, (v) => this.setRenderProp('name', v));\n}\n\n// in componentWillLoad():\n// nameProp.apply(this._name, (v) => this.setRenderProp('name', v));\n```\n\n- Eliminiert die Fehlerquelle bei neuen Props vollständig\n- Kein Scaffolding-Tool existiert aktuell im Projekt\n\n### Option C: JSDoc-Warnung auf `WebComponentInterface<T>` (minimal, sofort)\n\n```ts\n/**\n * @remarks\n * TypeScript erzwingt Felddeklarationen und Watcher-Methodensignaturen.\n * NICHT erzwungen werden: @Prop() Decorator, @Watch() Decorator, componentWillLoad() Forwarding.\n * Alle drei Teile des Prop-Dreiecks müssen manuell korrekt implementiert werden.\n */\nexport type WebComponentInterface<T extends ComponentApi> = ...\n```\n\n## Offene Punkte (Needs Deeper Look)\n\n- [ ] **Custom ESLint-Regel implementieren** für `@Prop()` + `@Watch()` Enforcement\n- [ ] **Code-Generator** für Prop-Dreieck-Boilerplate aus `propsConfig`\n- [ ] **`label` State-Disconnect im Skeleton** beheben — `@State label = 'Label'` im WebComponent und der Default in `propsConfig` sind unverbunden\n- [ ] **`@Watch('_name')` Typo-Risiko** — `@Watch('_nane')` wäre kein TypeScript-Fehler; ESLint-Regel würde das mit abdecken\n- [ ] **Alle Komponenten auditen** (`avatar`, `click-button`, `icon`, `image`, `progress`, `quote`) auf Prop-Dreieck-Vollständigkeit\n- [ ] **A11y-Tests** für Skeleton hinzufügen — kein `*.e2e.ts` / `*.spec.ts` vorhanden\n- [ ] **`event.preventDefault()` in `ClickButtonFC`** prüfen — blockiert alle Keyboard-Events (NVDA/JAWS-Test nötig)\n- [ ] **JSDoc `@remarks`** auf `WebComponentInterface<T>` in `generic-types.ts` ergänzen\n\n## Accessibility-Risiko\n\nBei fehlendem Prop-Wiring entsteht konkret eine WCAG-4.1.2-Verletzung (Name, Role, Value): Buttons erhalten keinen accessible name oder einen falschen Fallback-Text. `axe-core` würde dies in e2e-Tests fangen — aber nur wenn solche Tests existieren.\n",
3622
- "kind": "spec"
3623
- },
3624
3647
  {
3625
3648
  "id": "spec/abbr",
3626
3649
  "group": "spec",
3627
3650
  "name": "abbr",
3628
3651
  "description": "The Abbr component implements the HTML tag abbr.",
3629
3652
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/abbr.md",
3630
- "code": "# kol-abbr\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Abbr** component implements the HTML tag `abbr`.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ----------- |\n| `_label` | `_label` | DEPRECATED! Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------ |\n| | The abbreviation (short form). |\n\n\n----------------------------------------------\n\n\n",
3653
+ "code": "# kol-abbr\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Abbr** component implements the HTML tag `abbr`.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- |\n| `_label` | `_label` | DEPRECATED! Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------ |\n| | The abbreviation (short form). |\n\n\n----------------------------------------------\n\n\n",
3631
3654
  "kind": "spec"
3632
3655
  },
3633
3656
  {
@@ -3636,7 +3659,7 @@
3636
3659
  "name": "accordion",
3637
3660
  "description": "The Accordion component is a collapsible menu. Clicking the header area — consisting of an icon and a heading — expands the content to reveal additional information. It is an interactive navigation element designed to present extensive content in a space-saving manner.",
3638
3661
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/accordion.md",
3639
- "code": "# kol-accordion\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Accordion** component is a collapsible menu. Clicking the header area — consisting of an icon and a heading — expands the content to reveal additional information. It is an interactive navigation element designed to present extensive content in a space-saving manner.\n\nAccordions are used whenever content associated with a thematic heading needs to be shown or hidden. They allow more detailed information for a heading than would normally be practical, leaving it to the users to decide whether to view that information.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------- |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the callback functions for the collapsible. | `boolean \\| undefined` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nTriggers a click on the heading toggle button.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the content area of the accordion. |\n\n\n----------------------------------------------\n\n\n",
3662
+ "code": "# kol-accordion\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Accordion** component is a collapsible menu. Clicking the header area — consisting of an icon and a heading — expands the content to reveal additional information. It is an interactive navigation element designed to present extensive content in a space-saving manner.\n\nAccordions are used whenever content associated with a thematic heading needs to be shown or hidden. They allow more detailed information for a heading than would normally be practical, leaving it to the users to decide whether to view that information.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------- |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\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| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the callback functions for the collapsible. | `boolean \\| undefined` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nTriggers a click on the heading toggle button.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the content area of the accordion. |\n\n\n----------------------------------------------\n\n\n",
3640
3663
  "kind": "spec"
3641
3664
  },
3642
3665
  {
@@ -3645,7 +3668,16 @@
3645
3668
  "name": "alert",
3646
3669
  "description": "The Alert component provides visual feedback to users. It consists of a color-coded container, a heading, content text, and an icon. The icon used and the color scheme depend on the _type of the alert.",
3647
3670
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/alert.md",
3648
- "code": "# kol-alert\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Alert** component provides visual feedback to users. It consists of a color-coded container, a heading, content text, and an icon. The icon used and the color scheme depend on the `_type` of the alert.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------- |\n| `_alert` | `_alert` | Defines whether the screen-readers should read out the notification. | `boolean \\| undefined` | `false` |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the event callback functions for closing the alert. | `undefined \\| { onClose?: EventCallback<Event> \\| undefined; }` | `undefined` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"default\" \\| \"error\" \\| \"info\" \\| \"success\" \\| \"warning\" \\| undefined` | `'default'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"card\" \\| \"msg\" \\| undefined` | `'msg'` |\n\n\n## Slots\n\n| Slot | Description |\n| ---- | -------------------------------- |\n| | The content of the notification. |\n\n\n----------------------------------------------\n\n\n",
3671
+ "code": "# kol-alert\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Alert** component provides visual feedback to users. It consists of a color-coded container, a heading, content text, and an icon. The icon used and the color scheme depend on the `_type` of the alert.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------- |\n| `_alert` | `_alert` | Defines whether the screen-readers should read out the notification. | `boolean \\| undefined` | `false` |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the event callback functions for closing the alert. | `undefined \\| { onClose?: EventCallback<Event> \\| undefined; }` | `undefined` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"default\" \\| \"error\" \\| \"info\" \\| \"success\" \\| \"warning\" \\| undefined` | `'default'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"card\" \\| \"msg\" \\| undefined` | `'msg'` |\n\n\n## Slots\n\n| Slot | Description |\n| ---- | -------------------------------- |\n| | The content of the notification. |\n\n\n----------------------------------------------\n\n\n",
3672
+ "kind": "spec"
3673
+ },
3674
+ {
3675
+ "id": "spec/ARC42-SKELETON",
3676
+ "group": "spec",
3677
+ "name": "ARC42-SKELETON",
3678
+ "description": "The kol-skeleton component blueprint demonstrates how KoliBri web components can be built in a highly maintainable and decoupled fashion. It is designed as a minimal, yet complete, reference implementation for new components.",
3679
+ "path": "packages/tools/mcp/node_modules/@public-ui/components/docs/ARC42-SKELETON.md",
3680
+ "code": "# Skeleton Blueprint Architecture (arc42)\n\n## 1. Introduction and Goals\n\nThe `kol-skeleton` component blueprint demonstrates how KoliBri web components can be built in a highly maintainable and decoupled fashion. It is designed as a minimal, yet complete, reference implementation for new components.\n\nThe architecture is organized into **two layers** plus an optional reusable unit of logic:\n\n- **[Web Component (WC)](./web-components/skeleton/component.tsx)** — the orchestrator. It owns the Stencil lifecycle (`@Prop`/`@State`/`@Watch`/`@Method`), normalizes incoming props, manages reactive state, composes optional Behaviors, and feeds fully resolved render props to the Functional Component.\n- **[Behaviors](../../internal/functional-components/base-behavior.ts)** — optional, composable logic modules (e.g. `TooltipBehavior`). A WC may compose zero or more Behaviors. They manage their own render props but receive state access from their host WC.\n- **[Functional Component (FC)](../../internal/functional-components/skeleton/component.tsx)** — a pure, stateless renderer. It renders solely from the props handed to it and never mutates state.\n- **[Schema helpers](../../internal/props/)** — house prop types, normalization and validation helpers shared across layers.\n\nPrimary goals:\n\n- illustrate a minimal separation of concerns for long-term maintainability\n- keep the WC as the single orchestrator — no indirection layer between the custom element and the renderer\n- factor out only genuinely reusable cross-component logic into Behaviors\n- enforce consistent validation and type-safety boundaries\n- keep per-prop special treatment to a minimum — validation, defaults and hints are uniform across every component using a prop; deviations are documented exceptions with a reason, not per-component one-offs\n- document an end-to-end implementation pipeline that teams can replicate when bootstrapping new components\n\n### Blueprint Layout\n\nThe skeleton mirrors the structure recommended for production-ready components. Its web component definitions live in the regular `src/components/` folders (`click-button/`, `skeleton/`), while reusable internals (functional components, behaviors, prop schemas) reside in the shared `src/internal/` directory. Each folder holds a single responsibility to make the pipeline explicit:\n\n```text\nsrc/\n├── components/\n│ ├── click-button/ # Blueprint button web component\n│ │ ├── component.tsx # Orchestrator: props, watchers, lifecycle, render\n│ │ ├── interaction.e2e.ts # Interaction test (Playwright)\n│ │ └── snapshot.spec.tsx # Snapshot test (Jest) — co-located\n│ └── skeleton/ # Blueprint demo web component\n│ ├── component.tsx\n│ └── snapshot.spec.tsx\n└── internal/ # Shared internals\n ├── functional-components/\n │ ├── skeleton/ # Skeleton-specific logic\n │ │ ├── api.tsx # Type definitions + props config\n │ │ └── component.tsx # Stateless functional component\n │ ├── click-button/ # Reusable button FC\n │ │ ├── api.tsx\n │ │ └── component.tsx\n │ ├── tooltip/ # Tooltip behavior + FC\n │ │ ├── api.tsx\n │ │ ├── behavior.ts # TooltipBehavior\n │ │ └── component.tsx\n │ ├── bem-root-node/ # Single-root BEM wrapper FC\n │ │ └── component.tsx\n │ ├── base-behavior.ts # Shared behavior base class\n │ ├── base-web-component.ts # Shared WC base class (orchestrator helpers)\n │ └── generic-types.ts # Interface contracts\n └── props/ # Prop types, normalisation and validation\n ├── helpers/\n │ ├── factory.ts # Prop, SimpleProp, PropDefinition, apply()\n │ └── normalizers.ts # normalizeString, normalizeInteger, etc.\n ├── label.ts # LabelProp\n ├── name.ts # NameProp\n ├── show.ts # ShowProp\n └── index.ts # Re-exports\n```\n\nThis modular layout is the backbone for the architectural patterns described in the following chapters.\n\n### Usage Example\n\n```html\n<kol-skeleton _name=\"Example\"></kol-skeleton>\n```\n\n## 2. Architecture Constraints\n\n- **Stencil** is used for authoring web components with **shadow: true** only (Shadow DOM enabled for style isolation).\n- A component that embeds another component inside its own shadow DOM renders that component's **Functional Component** through an item (see §4 Embedded Components).\n- Components must compile to framework-agnostic Custom Elements.\n- Public API properties use an underscored naming convention (e.g. `_name`) to separate external inputs from internal state.\n- Documentation and code follow the `KoliBri` casing and repository conventions.\n\n## 3. Context and Scope\n\nThe skeleton lives inside `packages/components` and does not depend on runtime frameworks. External consumers interact through HTML attributes or DOM APIs.\n\n**Shadow DOM Strategy**: KoliBri uses Web Components with Shadow DOM enabled (`shadow: true`) by default. This ensures:\n\n- **Style Isolation**: Component styles cannot leak into host page styles and vice versa\n- **Encapsulation**: Components maintain consistent appearance regardless of host environment\n- **Maintainability**: Clear boundaries prevent unintended style interactions\n\n```mermaid\nflowchart LR\n Consumer[External Consumer] --> WC[Web Component]\n WC -.-> Schema[Schema Helpers]\n WC --> Behavior[Behavior, optional]\n WC --> FC[Functional Component]\n FC --> WC\n WC --> Consumer\n```\n\nThe external consumer interacts solely with the custom element. The WC is the orchestrator: it normalizes\nincoming values (consulting the schema helpers), composes optional Behaviors, and hands the resulting render\nprops to the stateless functional component. The resulting DOM is patched back into the WC and finally\nexposed to the consumer. Each arrow corresponds to an explicit TypeScript contract, ensuring that\nintegration points are discoverable and type safe.\n\n## 4. Solution Strategy\n\nThe blueprint enforces unidirectional data flow. The WC owns the full lifecycle: it normalizes props, manages reactive state, composes Behaviors, and renders. There is no controller/aspect class between the custom element and the FC.\n\n### Web Component Layer\n\nThe WC **is** the orchestrator. It extends `BaseWebComponent<Api>`, which provides:\n\n- `propsConfig` — the concrete component declares its props config as this field. The base seeds the render-prop store with its defaults on the first access, so even a `@Watch` fired by a prop assignment before `componentWillLoad` finds the defaults (#11449).\n- `setRenderProp(key, value)` / `getRenderProp(key)` — store and read normalized render props.\n- `setRawProp(key, value)` / `getRawProp(key)` — store/read the last raw (unprocessed) `@Prop` value, useful for change detection in watchers.\n- `stateAccess` — a `{ setState, getState }` bundle passed to composed Behaviors.\n- `stateLess` — a frozen sentinel for Behaviors that use no `@State`.\n\nResponsibilities of the WC:\n\n- Declares the public API using underscored props (e.g. `_name`).\n- Owns the Stencil-specific decorators (`@Prop`, `@Event`, `@Watch`, `@State`, `@Listen`). Watchers normalize incoming values via schema helpers and store them with `setRenderProp`.\n- Manages derived/UI state on `@State` fields, updated through `setState`/`getState` for reactivity.\n- Composes optional Behaviors (e.g. `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)`).\n- Renders the FC inside a bare `<Host>` (shadow DOM). No `<Host class=\"kol-…\">` — the tag name plus Shadow DOM are sufficient.\n\nA WC has **exactly one orchestrator (itself)** plus zero or more Behaviors. A WC may compose Behaviors, never other WCs.\n\nWhen several custom elements are tag variants of **one** FC (`kol-button`, `kol-button-link` and `kol-split-button` all render `ButtonFC`; `kol-link` and `kol-link-button` all render `LinkFC`), the orchestrator implementation is shared through an abstract base class next to the element (`components/button/base.tsx` → `BaseButtonWebComponent`, `components/link/base.tsx` → `BaseLinkWebComponent`). The base extends `BaseWebComponent<Api>`, carries no Stencil decorator and holds the composed Behaviors, the event handlers, one `apply<Prop>()` method per prop and the FC render call. The concrete element keeps everything Stencil has to see in the component class: `@Component`, `@Element`, `@State`, `@Method`, every `@Prop` with a one-line `@Watch` that calls the matching `apply<Prop>()`, and the lifecycle methods, which delegate to the base (see design decision 16).\n\n```tsx\n// WC — the orchestrator (KolLink, reference implementation)\nexport class KolLink extends BaseWebComponent<LinkApi> implements WebComponentInterface<LinkApi> {\n\tprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n\tprotected readonly propsConfig: PropsConfigShape = linkPropsConfig;\n\n\t@Prop() public _href!: string;\n\n\t@Watch('_href')\n\tpublic watchHref(value?: string): void {\n\t\threfProp.apply(value, (v) => this.setRenderProp('href', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\threfProp.apply(this._href, (v) => this.setRenderProp('href', v));\n\t\tlabelWithExpertSlotProp.apply(this._label, (v) => this.setRenderProp('label', v));\n\t\t// …all other props…\n\t\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<LinkFC\n\t\t\t\t\thref={this.getRenderProp('href')}\n\t\t\t\t\tlabel={this.getRenderProp('label')}\n\t\t\t\t\trefTooltip={this.tooltipBehavior.setTooltipElementRef}\n\t\t\t\t\t// …all other render props…\n\t\t\t\t/>\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n#### Member order\n\nEvery Stencil component class lists its members in the same order:\n\n1. `static` members\n2. `@Element`\n3. each `@State`, directly followed by its `@Watch` method(s) if it has any\n4. other fields (refs, behaviors, translations, items)\n5. `constructor`\n6. each `@Prop`, directly followed by its `@Watch` method(s); a watcher of several props follows the first of them\n7. `@Event`\n8. `@Method`\n9. lifecycle methods, grouped by phase (load, update, render, disconnect): `connectedCallback`, `componentWillLoad`, `componentDidLoad`, `componentShouldUpdate`, `componentWillUpdate`, `componentDidUpdate`, `componentWillRender`, `componentDidRender`, `disconnectedCallback`. This is a declaration convention, not the order in which Stencil runs the hooks (`componentWillRender` and `componentDidRender` run before `componentDidLoad`)\n10. `@Listen`\n11. helpers and handlers: the other methods, accessors and arrow-function fields, whatever their visibility\n12. `render`\n\nProperty initializers run in declaration order. A property whose value another initializer reads therefore stays before that property, even when its group comes later (e.g. `translateFilenameText` before the `@State` `filename` of `kol-input-file`). `component-structure.spec.ts` pins the member order of all components. For every class under `src` it also checks that no initializer reads an own property declared after it, directly (`this.x`), through own getters it reads (`this.derived`) or through own methods and arrow-function properties it calls (`this.compute()`), also nested through the called bodies. Every other path is not traced, e.g. a callee that receives `this` (`new Behavior(this)`), a synchronously run callback (an IIFE, `[1].map(() => this.later)`), `call`/`apply`/`bind` and element access (`this['x']`); keep such reads behind the property they read.\n\n### Public API Contract (Migration Parity)\n\nThe public API of a web component is exactly its set of `@Prop`/`@Method` members — for KoliBri\nthe underscored props (`_href`, `_label`, …) plus the public methods (`focus()`, `click()`, …) —\n**including** their JSDoc comments, their types, their defaults and any `@deprecated` markers.\n\n**Migration rule: the public API of a migrated component must be identical to its predecessor.**\nWhen refactoring a legacy component to the skeleton architecture, the migrated WC must expose the\nsame public members, with the same types (schema aliases, not downgraded primitives), the same\ndefaults and the same documentation. It must not add, remove, rename, retype or undocumented any\npublic member. A behavioural difference behind an unchanged member is a separate, consciously\nreviewed decision — never a side effect of the migration.\n\n**The FC's props are internal, not public API.** The functional component is an internal renderer\ncontract: it may offer more (or differently typed) props than the WC exposes. The WC is the API\ngate — it decides which render props are fed from public props and which stay at their internal\ndefaults. Never derive the public API from the FC's props, and never add a public `@Prop` \"because\nthe FC has one\". Conversely, internal-only capabilities (e.g. `ariaOwns`, `customClass`, `tabIndex`\non `LinkFC`) may stay unreachable from the outside when the predecessor component did not expose\nthem either.\n\n**Why the JSDoc is part of the contract:** `stencil build --docs` generates `docs-vscode`,\n`docs-readme` and — via `generateCustomElementsJson` — the `custom-elements.json` descriptors\ndirectly from `prop.docs` / `method.docs`. A `@Prop` without a JSDoc comment silently loses\nIntelliSense and generated documentation for every adapter package. The same applies to\n`@deprecated` markers, which announce planned removals to consumers.\n\n**Compile-time enforcement:** the WC implements the schema interface from `src/schema` (e.g.\n`implements LinkProps`) **in addition to** `WebComponentInterface<Api>`. The generic\n`WebComponentInterface` alone derives its prop types from the internal prop definitions\n(primitives like `string`/`boolean`), which would allow the public types to silently drift away\nfrom the schema. The schema alias types (`HrefPropType`, `LabelWithExpertSlotPropType`,\n`AlternativeButtonLinkRolePropType`, …) are structurally identical to the internal external types,\nso both `implements` clauses can coexist. Legacy state-shape requirements of `*API` types (e.g.\n`InternalLinkAPI`'s `state` member) are replaced by the render-prop store; implement the `*Props`\ninterface instead.\n\n**Verification (mandatory before merging a migration):** extract every `@Prop`/`@Method`\ndeclaration with its preceding JSDoc block from the predecessor file (`git show <base>:<path>`)\nand from the migrated file, and diff the two member lists. Any difference is a finding that needs\nan explicit justification in the PR description.\n\nThis is enforced continuously by the contract tests in\n[`src/components/public-api/`](../src/components/public-api/contract.ts): one `<component>.spec.ts` per component folder\nextracts the `@Prop`/`@Method` members (including JSDoc, types, defaults and requiredness) from the\ncomponent sources and compares them against a pinned contract, using the helpers in `contract.ts`.\n**Pin every component before its migration** (against the legacy `shadow.tsx`) and point the pin to\n`component.tsx` in the migration PR — the pin makes any public API change fail the build, which is\nexactly the point: such a change is a breaking change and must be an explicit, reviewable edit. One\nfile per component keeps parallel migrations free of merge conflicts.\n\n### Theming Contract (Shadow DOM Structure and BEM Classes)\n\nBesides the public API, a component exposes its rendered structure to themes: the nodes of its\nshadow DOM and the BEM classes on them, including a class on the host element. Themes, our own and\nthose of consumers, select these classes. This theming contract is versioned differently from the\npublic API:\n\n| Change | Classification | Release |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------- |\n| `@Prop`/`@Method`/`@Event`/slot, their types, defaults, documentation and behaviour, exported types | breaking change | major |\n| internal DOM structure (added, removed or moved nodes) and the BEM classes the structure needs (renamed, added, removed or moved classes) | **theming breaking change** | at least minor |\n\nA theming breaking change is not treated as a hard breaking change, because a theme can be adapted\nto it largely automatically: the theme's own visual snapshots show every affected selector, and the\n[`zero-visual-delta-handoff`](../../../../../.claude/skills/zero-visual-delta-handoff/SKILL.md) skill\ntogether with `pnpm check:skeleton-selectors` drives the theme back to zero pixel differences.\n\nRules for such a change:\n\n- The pull request adapts every theme of this repository in the same change, with zero pixel\n differences in the visual review.\n- It carries the release label `release:theming`, so the change appears in the changelog under\n _Theming_, and its title or description marks it as a **theming breaking change**.\n- The description lists each affected class or node with its old and new form, so theme authors\n can adapt their selectors.\n\n### Behavior Layer\n\nA Behavior is a reusable unit of logic that lives **inside** a WC. It extends `BaseBehavior<Api>` and:\n\n- Manages its own render props (`setRenderProp`/`getRenderProp`), seeded from its own props config in the `BaseBehavior` constructor.\n- Receives `StateAccess<Api>` from its host WC — either a real bundle or `BaseWebComponent.stateLess` when it manages no `@State`.\n- Exposes watcher entry points and lifecycle hooks (`componentWillLoad`) that the WC delegates to.\n- Must never instantiate other Behaviors directly — only the WC composes them.\n\nRule of thumb: a Behavior exists only when the same logic is genuinely shared across multiple components. The sole current example is `TooltipBehavior`, composed by link, button, and similar components.\n\n```tsx\n// Inside a WC\nprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n// delegating to the behavior from a watcher\nprivate applyTooltipAlign(value?: string): void {\n\ttooltipAlignProp.apply(value, (v) => {\n\t\tthis.setRenderProp('tooltipAlign', v);\n\t\tthis.tooltipBehavior.watchAlign(v);\n\t});\n}\n```\n\nFor a Behavior that has no `@State` fields, pass `BaseWebComponent.stateLess`:\n\n```tsx\nprivate readonly someStatelessBehavior = new SomeBehavior(BaseWebComponent.stateLess);\n```\n\n### Functional Component Layer\n\nThe FC is a pure renderer. It:\n\n- Receives normalized render props, callbacks, emitters and refs from the WC.\n- Avoids any side effects or state mutation. User interactions are signalled via DOM events/callbacks back to the WC.\n- Maps props to accessible markup and wires refs for imperative access when required.\n- May call stateless utility functions (e.g. `translate()`, formatters) directly — the `Callbacks` bucket in `ComponentApi` is reserved for event-driven callbacks only, not data accessors.\n\n#### BemRootNodeFC Pattern\n\nFCs use `BemRootNodeFC` to produce a single-root BEM structure. It renders exactly one `<div>` root node (enforcing a single-root FC), accepts a typed `block` name and `modifiers`, and merges an optional forwarded `class`:\n\n```tsx\nexport const LinkFC: FC<FunctionalComponentProps<LinkApi>> = (props) => {\n\tconst { disabled, inline, hideLabel, customClass, variant } = props;\n\t// …\n\treturn (\n\t\t<BemRootNodeFC\n\t\t\tblock=\"kol-link\"\n\t\t\tclass={clsx({ [customClass]: variant.includes('custom'), [classNameFromVariant(variant, 'link')]: variant.length > 0 })}\n\t\t\tmodifiers={{\n\t\t\t\tdisabled: disabled === true,\n\t\t\t\t'hide-label': hideLabel === true,\n\t\t\t\tinline: inline === true,\n\t\t\t\tstandalone: inline === false,\n\t\t\t}}\n\t\t>\n\t\t\t<a class=\"kol-link__interactive-element\" /* … */>…</a>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\nThe `block` and `modifiers` keys are validated against `KoliBriComponentsBemSchema`, so `block=\"kol-link\"` is type-checked and `modifiers={{ disabled: true }}` only accepts registered modifier keys. The output is `<div class=\"kol-link kol-link--disabled …\">`; inner elements use plain BEM element classes (`kol-link__interactive-element`, `kol-link__text`).\n\n**Registration requirement:** before using `BemRootNodeFC block=\"kol-xxx\"`, the block must be registered in `src/schema/bem-registry.ts` in **both** places — the exported `KoliBriComponentsBemSchema` type (required for compilation) and the runtime `BEM` const (consumed by the `kolibri-cli` SCSS generator). Type-only registration compiles and renders, but silently breaks theme SCSS generation.\n\n**When not to use it:** `BemRootNodeFC` always renders a `<div>` root. For FCs whose semantic root is another element (e.g. `ClickButtonFC` renders a `<button>`), build the root manually with `bem.forBlock('kol-xxx')(modifiers)` instead — the same typed schema applies. `LinkFC` and `ButtonFC` use `BemRootNodeFC` (both have extra siblings — tooltip, description — alongside their interactive element, so the wrapper is required, not just one non-div root); `SkeletonFC` and `ClickButtonFC` use direct `bem.forBlock` calls because their FC root _is_ the single non-div interactive element.\n\n### Embedded Components (Items)\n\nWhen a component renders another component inside its own shadow DOM — the close button of an alert, the sort buttons of a table, the page size select of a pagination — it renders that component's FC directly, so its own stylesheet and the theme reach the inner `.kol-…` classes. The orchestration the embedded element would own (resolved props with the element's `@Prop` defaults, Behaviors such as the tooltip, refs, event handlers) lives in an **item**: a plain object with closures, created once per embedded instance and owned by the embedding WC.\n\n| Item | Renders |\n| ---------------------------------------------------- | -------------------------------- |\n| `createButtonItem` (`button/item.ts`) | `ButtonFC` |\n| `createLinkItem` (`link/item.ts`) | `LinkFC` |\n| `createPopoverButtonItem` (`popover-button/item.ts`) | `PopoverButtonFC` |\n| `createDialogItem` (`dialog/item.tsx`) | `DialogFC` with a card |\n| `PageSizeSelect` (`pagination/page-size-select.tsx`) | the select field of `kol-select` |\n\n- `getFcProps(…)` returns the fully resolved FC props; call it once per render.\n- `syncListeners()` runs from `componentDidRender`, `destroy()` from `disconnectedCallback`.\n- A variable number of embedded instances (one action button per table row) goes through `createItemPool` (`item-pool.ts`): each render pass takes its items by key, and `endRender()` syncs them and destroys the ones the pass no longer used.\n- The KoliBri DOM events of the embedded component are dispatched on its FC root, where the embedded element used to be, so they bubble the same way.\n\n### Schema Helper Layer\n\nWeb components receive dynamic values from HTML attributes, but internal rendering requires statically typed data. The schema helper layer bridges that gap through **graceful degradation**: attempt minimal type conversion, then validate, but never force invalid data into types.\n\nDesign principles:\n\n- **Fail gracefully**: Invalid data is ignored rather than causing errors\n- **Minimal conversion**: Only obvious transformations (string numbers → numbers)\n- **Type guarantees**: Once validated, types are guaranteed throughout the component lifecycle\n- **Single source of truth for defaults**: Default values are defined explicitly in shared prop/schema helpers and consumed by components, avoiding duplicated or drifting defaults\n- **One definition per prop**: A public prop name has one definition in `internal/props` (e.g. `disabledProp` for every `_disabled`), reused by all components. A second definition for the same render key exists only where the props of different components differ functionally (other value type, value set or documented default), where a shared factory types the value per component (callbacks, links, options), or where the meaning of the prop differs (`labelWithExpertSlotProp` beside `labelProp`: its empty string enables the expert slot); `prop-keys.spec.ts` lists these variants with their reason. Definitions that share behavior share the implementation: under different keys `createAlignPropDefinition` (`_align`, `_popoverAlign`, `_tooltipAlign`), under one key the typed factories `createCallbacksPropDefinition`, `createLinksPropDefinition` and `createOptionsPropDefinition`\n- **One explicit schema type per prop**: every prop value type is the named schema type from `src/schema/props`; as a rule, one readable PropType per functionality is shared by all of its property definitions, and prop bags, prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining a native type (see _Explicit Schema Types per Prop_)\n- **As few special treatments per prop as possible**: a prop's validation, default and hints are the same for every component using it; a component-specific deviation is a documented exception with a reason (e.g. the `LabelWithExpertSlotPropType` empty-string sentinel), never a silent one-off (see §1 Primary Goals)\n\n#### Dual-Type Props\n\nEach prop can define an **external** (Web Component API) and an **internal** (FC) type. The external type may be more permissive to support shorthand values from HTML attributes, while the internal type is always the normalized form.\n\n`Prop<K, TExternal, TInternal>` encodes both via phantom keys (`__input_${K}` carries the external type, `__propInternal__` carries the internal type). `SimpleProp<K, T>` is a shorthand when both types are identical:\n\n```typescript\n// Different external and internal types:\ntype ColorProp = Prop<'color', ColorPair | string, ColorPair>;\n// └─ Key └─ Web Component └─ FC\n\n// Same external and internal type (shorthand):\ntype NameProp = SimpleProp<'name', NamePropType>;\n// └─ Key └─ Both types\n```\n\n#### Explicit Schema Types per Prop\n\nEvery prop has exactly one named **schema type** in `src/schema/props` (e.g. `DisabledPropType` in\n`schema/props/disabled.ts`). A schema type may be structurally as simple as a native type — naming it\nis the point, not making it complex. The name is the single spelling of the type: the prop bag, the\nprop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all\nreference it, and no layer inlines a native type instead:\n\n```typescript\n// schema/props/disabled.ts — the named schema type (its structure does not change)\nexport type DisabledPropType = boolean;\n\n// internal/props/disabled.ts — the definition references the schema type\nexport type DisabledProp = SimpleProp<'disabled', DisabledPropType>;\nexport const disabledProp = createPropDefinition<DisabledProp>('disabled', false, normalizeBoolean);\n\n// components/button/component.tsx — @Prop, watcher and apply carry the schema type\n@Prop() public _disabled?: DisabledPropType = false;\n\n@Watch('_disabled')\npublic watchDisabled(value?: DisabledPropType): void {\n\tdisabledProp.apply(value, (v) => this.setRenderProp('disabled', v));\n}\n```\n\nOne caveat lives in the test toolchain, not in the compiled output: the pinned Stencil transpile does\nnot coerce attribute strings for imported type aliases\n([stenciljs/core#4663](https://github.com/stenciljs/core/issues/4663), fixed upstream), so jest sees\nthe raw attribute string on an aliased boolean/number prop while the compiled dist metadata resolves\nthe alias and the real runtime is unaffected. Tests therefore assert the normalized render props\ninstead of raw `@Prop` values; the next Stencil upgrade removes the caveat entirely.\n\nWithout the shared name, every layer spells the type its own way (`SimpleProp<'disabled', boolean>`,\n`watchDisabled(value?: boolean)`) and nothing ties the spellings together. With it, `apply`, watcher\nand FC signatures carry the domain term, drift between the layers fails the compiler instead of\nsurfacing in review, and an evolution of the schema type moves every layer at once.\n\nAs a rule, one readable PropType is defined per functionality and shared by all of its property\ndefinitions — whether there is one (`disabledProp` for `_disabled`) or several (`inputDateMaxProp`,\n`inputMaxProp`, `maxProp` and `paginationMaxProp` for `_max`, each with its own normalizer,\nvalidator or default). The shared type — not only the prop key string — is what connects the\ndefinitions of a functionality. Only in individual cases, where the meaning of the value itself\ndiffers, is a special readable PropType variant introduced — e.g. `LabelWithExpertSlotPropType`\nbeside `LabelPropType`, or the distinct `_value` types of the checkbox, radio, select, date and\nnumber inputs. `prop-keys.spec.ts` documents the variants per render key.\n\nNaming roles stay distinct: `XxxPropType` is the schema value type, `PropXxx` the schema prop bag\nand `XxxProp` the prop definition in `internal/props`.\n\nWhich variant a component uses follows its rendered markup: a `_label` that flows into the `span`\nexpert slot (`<slot name=\"expert\">`) is `LabelWithExpertSlotPropType` — the interactive elements,\nthe form-field labels and the heading (its label sits in the heading tag next to the expert slot).\nA `_label` that is a landmark name, a caption or a pure `aria-label` without an expert slot stays\n`LabelPropType` — even when the component renders unrelated expert slots elsewhere (e.g. for the\nquote content or the tree item button). The decisive test is who switches the slot: a label is a\nsentinel carrier (`''` enables the slot) only where the label value itself toggles it. A label\nrendered through a slot the component keeps open on its own — the tree item puts its label into\nthe always-open expert slot of its embedded link — carries segments but no sentinel, so it binds\n`labelLangSegmentsProp`.\n\nThis rule binds new and changed props immediately. Existing props adopt it family by family — prop\ndefinitions first, then component signatures. Where no named schema type exists yet, it is added: an\nadditive, non-breaking change, because naming a type never changes its structure.\n\n#### Label Handling Forms\n\nSix forms govern how a label value flows through the layers. They exist because the validation\nboundary and the render boundary are different places: the web component validates untyped input\n(attributes arrive as strings, adapters pass any runtime value), while a functional component\nreceives already-normalized props and never validates.\n\n1. **A functional component trusts its props.** Its prop type comes from the props config slot\n (`required` → mandatory, `optional` → partial). A guard inside a functional component is never a\n distrust of validation — it handles the documented \"not set\" state of an optional prop (the alert\n without a label renders no heading).\n2. **The \"not set\" guard is `label?.length > 0`** for optional `string | LabelSegment[] | undefined`\n labels, in JSX conditions and ternaries alike. The expression must be strictly boolean: a bare\n `label?.length &&` renders the digit `0` into the DOM when the label is the empty string.\n3. **`trimLabel(label)` is the only way to obtain a plain string** (accessible names, aria-label,\n aria-description). `trimLabel` is undefined-safe by signature (`undefined` → `''`) and the only\n place joining segment arrays — call it without `?? ''` or `|| ''`, and never apply string\n operations to a segment array directly.\n4. **`''` is the expert-slot sentinel, everywhere.** Only components with `labelWithExpertSlotProp`\n accept it; their span switches to the expert slot. Everywhere else it is an invalid value. The\n one mapping to \"not set\" lives where an empty label is legitimate input (the tooltip behavior:\n `apply(value || undefined, …)`, mapping `''` to the unset state instead of an invalid-value\n warning).\n5. **Rendered labels go through `renderLabelWithLang`** so each segment keeps its `lang` attribute\n for screen readers. A pure `aria-label` uses `trimLabel` — language segments would have no\n effect there, which is why landmark components bind `labelProp`.\n6. **Which prop definition a component binds follows its markup** (see the variant rule above);\n the forms here stay identical for all three label definitions.\n\n#### `PropDefinition<TInternal>`\n\n`PropDefinition<TInternal>` defines `normalize` (unknown → TInternal), `validate` (TInternal → boolean), `getDefaultValue()` (→ TInternal) and `apply(value, callback)`. The normalize function accepts `unknown` because HTML attributes can arrive as any type.\n\nEach `PropDefinition` provides an `apply(value, callback)` method that combines normalization, validation and fallback handling into a single call. If the value is `undefined` or `null`, the built-in default is used. Otherwise, the value is normalized and validated before being passed to the callback — ensuring callbacks only receive type-safe internal values:\n\n```typescript\nmaxProp.apply(value, (normalized) => {\n\t// normalized is number, type-safe and validated (> 0)\n\tthis.setRenderProp('max', normalized);\n});\n```\n\n##### Undefined handling, requiredness and the default contract\n\nThree rules separate the layers, so a fachliche validator never has to deal with \"not set\":\n\n1. **Requiredness is a property of the component, decided by the props config slot.** The `required`/`optional` arrays feed `ApiFromConfig` (`Props.Required`/`Props.Optional`) _and_ drive the runtime warning: `BaseWebComponent.isRequired(key)` answers from the `required` array, and the applying watcher passes it to `apply` as its third argument (`labelProp.apply(value, cb, this.isRequired('label'))`). A prop definition itself carries no requiredness — one definition serves a required prop in one component (the link's `href`) and an optional one in another (the card's) without duplication. Appliers outside a component config (items, behaviors, `resolve-props`) apply without the argument: an unset value there is a legitimate \"not set\", not a missing required value.\n2. **`apply()` intercepts `undefined` and `null` before any fachliche validation**: after the warning when `required` was passed, the built-in default is substituted and handed to the callback. `normalize` and `validate` never see a raw `undefined` from the `apply` path.\n3. **A definition with a default must accept it as a value; a definition without a default has no fallback at all.** `createPropDefinition` takes `undefined` as a deliberate \"no default\": an unset value then flows through as \"not set\" — nothing is validated, the validator only ever sees real values (e.g. `isValidLabel` checks length only). A definition that does carry a default has its fallback validated and throws on an invalid one. Either way the fachliche validation of real values stays untouched by the \"not set\" state. The factory types this guarantee: a definition created with a default exposes a non-optional `getDefaultValue(): TInternal` (`PropDefinitionWithDefault`), so callers read the fallback without assertions.\n\n#### `DependentPropDefinition<TInternal, TDeps>`\n\nSome props require context from other props to normalize or validate correctly. `createDependentPropDefinition` extends the pattern with a `TDeps` parameter passed through to both `normalize` and `validate`. Its `apply` method takes the deps object as a third argument:\n\n```typescript\nclampedNumberValueProp.apply(\n\tvalue,\n\t(normalized) => {\n\t\tthis.setRenderProp('value', normalized);\n\t},\n\t{ min: 0, max: this.getRenderProp('max') },\n);\n```\n\n#### Type Extraction\n\n`InternalOf<P>` and `ExternalOf<P>` utility types extract the correct type for each architectural layer automatically:\n\n| Layer | Type Extractor | Example (`ColorProp`) |\n| -------------------- | -------------- | --------------------- |\n| WC `@Prop` | `ExternalOf` | `ColorPair \\| string` |\n| `@Watch` handler | `ExternalOf` | `ColorPair \\| string` |\n| WC `setRenderProp` | `InternalOf` | `ColorPair` |\n| WC `getRenderProp` | `InternalOf` | `ColorPair` |\n| Functional Component | `InternalOf` | `ColorPair` |\n\n### API Definition with `PropsConfigShape` and `ApiFromConfig`\n\nComponent APIs are defined using a runtime props config object (`PropsConfigShape`) that groups prop definitions into `required` and `optional` arrays. The `ApiFromConfig<Config, Extra>` utility type derives the full `ComponentApi` type from this config, making the props config the single source of truth for both runtime behaviour (normalization, validation, defaults) and compile-time types:\n\n```ts\nexport const skeletonPropsConfig = {\n\trequired: [nameProp],\n} as const satisfies PropsConfigShape;\n\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tMethods: { focus: () => void; toggle: () => void };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n`ApiFromConfig` automatically merges the phantom prop types from the config arrays into the `Props.Required` and `Props.Optional` fields. The WC declares the same config object as its `propsConfig` field, from which the base derives the initial render-prop defaults.\n\nThe contracts between layers are formalized through TypeScript interfaces in [`generic-types.ts`](../../internal/functional-components/generic-types.ts). These generics (`WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps`) guarantee that components share a consistent shape for props, callbacks, emitters and refs.\n\n### Methods and Automatic Promise Wrapping\n\nStencil requires that all public `@Method()` decorated methods return a `Promise`. To keep API definitions concise, `ComponentApi` allows method signatures to be defined with plain return types. The `PromiseMethod<Methods>` utility type automatically wraps each method's return type in `Promise<T>` via `WebComponentInterface`:\n\n```ts\n// API definition — simple, no Promise required\nMethods: {\n focus: () => void;\n getValue: () => number;\n};\n```\n\n```ts\n// Resolved in WebComponentInterface — automatically Promise-wrapped\nfocus: () => Promise<void>;\ngetValue: () => Promise<number>;\n```\n\n`BehaviorInterface` intentionally does **not** apply `PromiseMethod` wrapping — Behaviors stay synchronous and testable, and the `async`/`Promise.resolve()` wrapping happens at the WC layer.\n\n### Event Handler Policy\n\nWC and Behavior methods follow a clear convention based on their usage pattern:\n\n- **Callbacks, event handlers, and ref setters** are declared as **arrow class properties** (`handleClick = () => { … }`). This auto-binds them to the instance, so they can be safely passed as references without `.bind(this)` or wrapper arrows.\n- **Lifecycle methods, watchers, and public API methods** (`componentWillLoad`, `watchName`, `focus`, `toggle`) remain **prototype methods** shared across all instances for memory efficiency.\n\nBecause callbacks are already arrow properties, both render patterns are valid:\n\n```tsx\n// Pattern A: Pass arrow property directly (concise)\n<ClickButtonFC handleClick={this.handleClick} refButton={this.setButtonRef} />\n\n// Pattern B: Wrap in arrow for explicit forwarding (allows intermediate logic)\n<SkeletonFC handleClick={() => this.handleClick()} refButton={(el) => this.setButtonRef(el)} />\n```\n\n#### ⚠️ Never use `.bind(this)` with `addEventListener`/`removeEventListener`\n\nArrow function properties automatically bind `this` at definition time. **Never** create new bound instances with `.bind(this)` in DOM event registration, as this causes listener accumulation and memory leaks — `addEventListener` and `removeEventListener` must receive the **exact same function reference** to match. Use an arrow property, or a ref callback that removes the old listener before adding the new one (see `src/components/popover-button/base.tsx`, `handleToggle` + `componentDidRender`/`disconnectedCallback`).\n\n### Implementation Flow\n\n1. **Initialisation** – the base seeds the render-prop store with the defaults of `propsConfig` on the first access — earliest possible point is a `@Watch` fired by a prop assignment before `componentWillLoad`. `componentWillLoad` applies the current prop snapshot, ensuring render props reflect external values before the first render. Composed Behaviors are initialized here too.\n2. **Prop updates** – `@Watch` handlers receive raw values, normalize/validate them via schema helpers, and store the result with `setRenderProp`.\n3. **Rendering** – the WC reads render props via `getRenderProp` and feeds them into the FC.\n4. **User interaction** – the FC emits DOM events / calls callbacks. The WC wires these back into its own handlers (or Behavior methods) so state transitions remain encapsulated.\n\n### Props Pattern\n\nA critical design principle is that **functional components always render using Props**, which are either:\n\n1. **Normalized and validated external props** — incoming props processed through schema helpers\n2. **Internal component state** — derived or computed values managed by the WC via `@State`\n\nThis ensures the renderer never works with raw, unvalidated data. Props must always be initialized before being passed to the FC (the seeding from `propsConfig` on the first access guarantees this).\n\n### Watcher Example\n\nIncoming props are normalized in dedicated watchers directly inside the WC:\n\n```ts\n// Prop definition (internal/props/name.ts); NamePropType is imported from schema/props/name.ts\ntype NameProp = SimpleProp<'name', NamePropType>;\nconst nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n```tsx\n// Web Component (web-components/skeleton/component.tsx)\n@Prop() public _name!: NamePropType;\n\n@Watch('_name')\npublic watchName(value?: NamePropType): void {\n\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n}\n```\n\nThe `apply()` method uses the default value built into `nameProp` when the incoming value is `undefined` or `null`.\n\n### WC State Management\n\nThe WC manages two kinds of state directly:\n\n**Normalized Props** (via `setRenderProp()`):\n\n- Stored in the render-prop map after validation\n- Updated by watchers (e.g. `watchName`)\n- Never trigger Stencil re-renders on their own\n- Retrieved via `getRenderProp(key)` for rendering\n\n**Derived/Managed State** (via `@State` + `setState()`/`getState()`):\n\n- Stored in `@State` fields on the WC\n- Used for computed or UI state (e.g. `count`, `show`, `ariaCurrent`)\n- Each `setState()` assignment triggers a Stencil re-render\n- Read back with `getState(key)`\n\n**Rule**: a prop watcher should call `setRenderProp()` to store the normalized value. Add a `setState()` call only for `@State` fields that require reactive updates. This minimizes re-renders while keeping code clear:\n\n```tsx\n@Watch('_name')\npublic watchName(value?: string): void {\n\tnameProp.apply(value, (v) => {\n\t\tthis.setRenderProp('name', v); // Store normalized prop (no re-render)\n\t\t// this.setState('name', v); // Add only if 'name' is also an @State field\n\t});\n}\n```\n\n### WC Initialization\n\nThe WC declares its props config as the `propsConfig` field; the base seeds the render-prop store from it on the first access. `componentWillLoad` applies the current prop values and initializes composed Behaviors:\n\n```tsx\n// Web Component\nprotected readonly propsConfig: PropsConfigShape = skeletonPropsConfig;\n\npublic componentWillLoad(): void {\n\tnameProp.apply(this._name, (v) => this.setRenderProp('name', v));\n\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n}\n```\n\n## 5. Building Block View\n\n```mermaid\nclassDiagram\n direction LR\n class WebComponent {\n +componentWillLoad()\n +watchName()\n +render()\n #setState(key, value)\n #getState(key)\n #setRenderProp(key, value)\n +getRenderProp(key)\n }\n class TooltipBehavior {\n +componentWillLoad(props)\n +watchLabel(value)\n +watchAlign(value)\n +getRenderProp(key)\n }\n class LinkFC {\n +render(props)\n }\n class SchemaHelpers {\n +nameProp.apply()\n +labelProp.apply()\n }\n WebComponent ..> SchemaHelpers : normalizes via\n WebComponent --> LinkFC : renders with render props\n WebComponent o--> TooltipBehavior : composes, optional\n```\n\n**Web Component** — implements `WebComponentInterface`, owns the lifecycle, normalizes props, manages reactive state, composes optional Behaviors, and renders the FC.\n\n**TooltipBehavior** — implements `BehaviorInterface`, encapsulates a single reusable concern (tooltip show/hide, listener syncing, positioning). Composed by any WC that needs it.\n\n**LinkFC** — implements `FunctionalComponentProps`, receives the render props and produces JSX without touching state.\n\n**Schema helpers** — provide deterministic data normalization and validation functions reused across all WCs.\n\n## 6. Runtime View\n\nThe following sequence demonstrates how an external update is normalized and validated before it propagates to the renderer. The WC handles normalization directly — there is no intermediate layer.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant WC as WebComponent\n participant FC as FunctionalComponent\n participant S as Schema\n U->>WC: set attribute _name=\"Alice\"\n WC->>S: nameProp.apply(\"Alice\", callback)\n S->>S: normalize(\"Alice\") → \"Alice\"\n S->>S: validate(\"Alice\") → true\n S-->>WC: callback(\"Alice\")\n WC->>WC: setRenderProp('name', \"Alice\")\n WC->>FC: render(renderProps)\n FC-->>WC: markup\n WC-->>U: updated DOM\n Note over S,WC: apply() combines normalize + validate + callback\n Note over WC,FC: renderProps contain normalized/validated data or @State\n```\n\nThis runtime view highlights how the WC normalizes and validates external values before any rendering occurs. Only after the WC updates its render props does it invoke the functional component, patch the returned markup and expose the updated DOM to the user.\n\n## 7. Deployment View\n\nThe skeleton ships as part of the `@public-ui/components` package. During build the Stencil compiler produces framework-agnostic bundles ready for distribution via npm or CDN.\n\n## 8. Cross-cutting Concepts\n\n| Concept | Description |\n| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Composition over inheritance** | WCs compose Behaviors (e.g. `TooltipBehavior`) for reusable logic rather than relying on inheritance. |\n| **Orchestrator WC** | The WC is the single orchestrator: it normalizes props, manages state, and renders. No controller/aspect class sits between the element and the FC. |\n| **BemRootNodeFC pattern** | FCs render a single root `<div>` via `BemRootNodeFC`, with a type-checked `block` and `modifiers`. Produces `<div class=\"kol-block kol-block--…\">`; inner elements use BEM element classes. |\n| **Embedded components through items** | A component that embeds another component in its own shadow DOM renders that component's FC directly; an item (`createButtonItem`, …) owns the orchestration of each embedded instance. |\n| **Declarative rendering** | Functional components are pure and stateless. |\n| **Event-driven communication** | User interaction is emitted as DOM events/callbacks rather than calling functions across layers. |\n| **Props Pattern** | Functional components exclusively receive Props that contain either normalized/validated external data or internal component state. Props must always be initialized. |\n| **Shadow DOM First** | WCs use `shadow: true`; `shadow: false` is reserved for the transitional pattern. Components that never need an element wrapper are plain FCs. |\n| **ARIA ID Uniqueness via readable nonce IDs** | Any DOM `id` referenced by ARIA attributes (e.g. `aria-controls`, `aria-labelledby`) must be unique per component instance and follow the pattern `readable-identifier-<nonce>`. Use `private readonly someId = createUniqueId('readable-identifier')` from `utils/dev.utils`. This prevents ID collisions when components are composed inside a shared DOM scope (e.g. multiple WC instances within one shadow root, or direct light-DOM usage). Shadow DOM alone is not sufficient when a shadow component renders multiple instances of an internal WC in the same shadow root. |\n| **State ownership** | The WC owns reactive state (`@State`) and render props; the FC consumes them. |\n| **Type safety** | `WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps` encode compile-time contracts between layers. |\n| **Explicit schema types** | Every prop has exactly one named schema type in `src/schema/props`; prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining native types (the stenciljs/core#4663 alias caveat is confined to the jest toolchain). |\n| **Styling boundary** | A component's `style.scss` is base styling: layout and structure only, no colors (except the black/white contrast fallback), no spacing and no dark/light color scheme (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Colors, spacing and color schemes are implemented in the theme packages. See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](../../../../../docs/BASE_STYLING_VS_THEMING_CONCEPT.md). |\n| **Watcher placement** | Attach `@Watch` only to underscored public props (e.g. `_name`); internal state fields use `@State`. |\n\n## 9. Design Decisions\n\n1. **Eliminate the Aspect layer**\n - _Previous architecture_: a separate `BaseAspect` class sat between the WC and the FC (`WC → Aspect → FC`).\n - _Reason_: the relationship was strictly 1 WC : 1 Aspect, so the Aspect was pure indirection — every watcher and render-prop access was a pass-through. The WC can manage render props directly (the base seeds them from the declared `propsConfig` field on first access; reads and writes go through `getRenderProp`/`setRenderProp` on `BaseWebComponent`). Removing the layer halves the number of classes per component, removes a constructor/`StateAccess` handoff, and keeps the data flow in one place. Only genuinely composable, cross-component logic survives as a `Behavior`.\n2. **Behaviors for genuinely shared logic only**\n - _Alternative_: also extract per-component logic into a dedicated behavior/controller.\n - _Reason_: a Behavior earns its existence only when the same logic is reused across multiple components (e.g. `TooltipBehavior`). Single-use logic stays as private methods on the WC.\n3. **Underscored public props**\n - _Alternative_: mirror external props directly without underscores.\n - _Reason_: underscores make the separation between public API and internal state explicit.\n4. **Shadow DOM enabled for web components (shadow: true)**\n - _Alternative_: allow some components to have `shadow: false`.\n - _Reason_: Shadow DOM ensures consistent style isolation and prevents CSS conflicts from host page styles, eliminating a category of hard-to-debug styling issues.\n5. **Embedded components render their FC through items**\n - _Alternative_: render a `shadow:false` element (`kol-button-wc`, …) inside the embedding component's shadow DOM, so its stylesheet reaches the inner `.kol-…` classes.\n - _Reason_: such an element duplicates the orchestrator of the public element and puts an extra node between the embedding component and the embedded block. An item keeps one orchestration per embedded instance in the embedding WC and renders the FC root in place of the element.\n6. **Centralised validation in the WC**\n - _Alternative_: perform validation scattered inside prop watchers without schema helpers.\n - _Reason_: routing all external values through `PropDefinition.apply()` keeps validation, defaults and normalization in one reusable, testable place.\n7. **Functional component rendering**\n - _Alternative_: render JSX directly inside the web component class.\n - _Reason_: a pure renderer improves testability and eliminates side effects.\n8. **Generic interface contracts**\n - _Alternative_: rely on ad-hoc typing per component.\n - _Reason_: shared interfaces keep props, callbacks, emitters and refs uniform across components, making WCs, Behaviors and renderers interchangeable.\n9. **@State for managed UI state, render props for normalized props**\n - _Pattern_: public props (e.g. `_name`) are normalized and stored as render props. UI state that is managed but not exposed as props (like `count`, `show`, `ariaCurrent`) uses `@State` to trigger reactive re-renders.\n - _Reason_: normalized props do not need `@State` — they are held as render props and accessed via `getRenderProp(key)`. This avoids unnecessary re-rendering while keeping reactive state explicit.\n10. **Host element without redundant class attribute**\n - _Alternative_: add the component name as a class attribute to `<Host>` (e.g. `<Host class=\"kol-skeleton\">`).\n - _Reason_: the tag name alone (e.g. `<kol-skeleton>`) plus Shadow DOM are sufficient for styling and identification. The BEM root class is emitted by `BemRootNodeFC` inside the FC, not on `<Host>`.\n11. **Omit unused API fields in ComponentApi definitions**\n - _Pattern_: all fields in `ComponentApi` are optional except `States` (`Props`, `Emitters`, `Methods`, `Callbacks`, `Refs`, `Listeners` — `States` is required and defaults to `Record<never, never>` via `ApiFromConfig`). Only define the fields the component actually uses. The generic type extraction in `generic-types.ts` safely defaults missing fields to empty records.\n - _Alternative_: define all fields explicitly, using empty records for unused ones.\n - _Reason_: a minimal API definition is easier to read and accurately conveys what the component does.\n12. **ARIA ID uniqueness via `createUniqueId()`**\n - _Pattern_: any `id` referenced by an ARIA relation attribute must be unique per instance. Declare stable base ids as `private readonly xId = createUniqueId('x')` and derive related ids with `createRelatedUniqueId(baseId, 'control')`.\n - _Alternative_: hardcode a static string.\n - _Reason_: Shadow DOM scopes IDs per shadow root, but a parent may render multiple instances of an internal WC in the same shadow root, colliding IDs. `createUniqueId()` is cheap and eliminates this category of bug, and also covers direct light-DOM usage.\n13. **No `data-testid` — use BEM class selectors in tests**\n - _Pattern_: do not add `data-testid` attributes. Tests select elements via their BEM class names (`page.locator('.kol-component__element')`).\n - _Alternative_: add `data-testid` and use `getByTestId()`.\n - _Reason_: BEM class names are already present, stable, and semantically tied to the component. Using them keeps production markup clean of test-only concerns.\n14. **Test co-location — all tests live next to the component**\n - _Pattern_: all test files sit directly alongside `component.tsx` — snapshot tests (`snapshot.spec.tsx`, Jest) and interaction tests (`interaction.e2e.ts`, Playwright). File names are uniform across components.\n - _Alternative_: group tests into a dedicated `test/` subdirectory.\n - _Reason_: co-located tests are easier to discover and keep related files visible side-by-side.\n15. **Public API parity during migration — the FC face is not the public face**\n - _Pattern_: a skeleton migration keeps the WC's public `@Prop`/`@Method` set byte-identical to the predecessor: same members, same schema-alias types, same defaults, same JSDoc (including `@deprecated`). The WC implements the schema `*Props` interface alongside `WebComponentInterface<Api>` so drift fails the build. Internal FC props without a public predecessor prop stay internal (fed from defaults, no public `@Prop` added).\n - _Alternative_: expose every FC prop 1:1 as a public `@Prop` and declare props with the internal primitive types.\n - _Reason_: the public API is a compatibility contract (adapters, IntelliSense, `custom-elements.json` are generated from `prop.docs`/`method.docs`). Growing it silently (e.g. link gained `_ariaOwns`, `_customClass`, `_tabIndex`, `click()`) or dropping its documentation is a breaking change disguised as a refactor. See [§4 Public API Contract](#public-api-contract-migration-parity).\n16. **Shared orchestrator base for tag variants of one FC**\n - _Pattern_: elements that render the same FC (`kol-button`/`kol-button-link`/`kol-split-button`, `kol-link`/`kol-link-button`) share an abstract, decorator-free base class next to the element (`button/base.tsx`, `link/base.tsx`) that extends `BaseWebComponent<Api>` and holds Behaviors, handlers, `apply<Prop>()` methods and the FC render call. The concrete element declares the Stencil members and delegates from its watchers and lifecycle methods.\n - _Alternative_: copy the orchestrator into every element (the state before this decision: ~350 identical lines in `component.tsx` and `wc.tsx`), or let the variants instantiate a `shadow:false` twin of the public element.\n - _Reason_: the base is not a layer between WC and FC (decision 1 stays intact) — it _is_ the WC's implementation, written once. Stencil only reads decorators and lifecycle hooks from the component class itself, so those stay there; plain methods and fields are inherited at runtime like the ones of `BaseWebComponent`. Anything that needs the host element (e.g. the form-association controller) is created from the concrete constructor after `super()`, because Stencil registers the host at the start of the component class's constructor.\n17. **DOM structure and BEM classes are a theming contract, not public API**\n - _Pattern_: a change of the internal DOM structure or of the BEM classes it needs ships in at least a minor release as a **theming breaking change**: release label `release:theming`, old and new classes listed in the pull request, all themes of this repository adapted in the same change. See [Theming Contract](#theming-contract-shadow-dom-structure-and-bem-classes).\n - _Alternative_: treat every class or node change as a breaking change that waits for the next major release.\n - _Reason_: themes can be adapted to such a change largely automatically through their own visual snapshots and the zero-visual-delta workflow. Holding back structural cleanups (single BEM root, registered classes) until a major release would keep known non-conformities alive for a long time without protecting anyone more than the changelog entry does.\n18. **Explicit schema types per prop**\n - _Pattern_: every prop's value type is the named schema type from `src/schema/props`; the prop bag, the prop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all reference that name, and no layer inlines a native type. See [Explicit Schema Types per Prop](#explicit-schema-types-per-prop).\n - _Alternative_: type prop definitions and component signatures with bare natives (`SimpleProp<'disabled', boolean>`) and keep the schema name only on the prop bag.\n - _Reason_: the type is defined once and every layer points at the same name, so drift between the layers fails the compiler instead of surfacing in review; apply and watcher signatures carry the domain term; and the prop definitions binding one render key are connected by their shared schema type, not only by the key string. Naming a type never changes its structure, so adopting it is invisible to consumers. The pinned Stencil's un-coerced attribute parsing for imported aliases (stenciljs/core#4663) is a known test-toolchain caveat, not a reason to inline natives.\n\n## 10. Quality Requirements\n\n- Maintainability: the WC is the single orchestrator, reducing the number of classes and the cost of change.\n- Reliability: schema helpers validate every external value before it mutates state.\n- Testability: the FC is a pure renderer and can be unit tested in isolation; Behaviors can be tested standalone. Snapshot tests (Jest) verify DOM output; interaction tests (Playwright) verify user-facing behaviour.\n- Performance: **optimized re-rendering** — public props are normalized and stored as render props (no re-render); only `@State` changes trigger re-renders. Stencil batches simultaneous prop/state changes into a single re-render.\n- Accessibility: follow repository-wide a11y presets and prefer `KolTooltip` over `title` attributes.\n- Security: avoid direct DOM injection; rely on typed props and validation to prevent XSS.\n\n## 11. Risks and Technical Debt\n\n- The transitional `shadow:false` WCs are temporary scaffolding; they should be removed as consumers migrate to render FCs directly.\n- WCs with many props can accumulate verbose watcher boilerplate; the `PropDefinition.apply()` pattern keeps each watcher to one line, but a component with dozens of props still produces dozens of watchers.\n- Behaviors that hold listener references must clean up in `disconnectedCallback` to avoid leaks (see the Event Handler Policy warning).\n\n## 12. Glossary\n\n| Term | Definition |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **BEM** | Block Element Modifier naming convention for CSS class names. |\n| **BemRootNodeFC** | Single-root BEM wrapper FC. Renders one `<div class=\"kol-block kol-block--…\">` from a type-checked `block` and `modifiers`. |\n| **Behavior** | Optional, composable unit of reusable logic living inside a WC; extends `BaseBehavior`. Example: `TooltipBehavior`. |\n| **Orchestrator (WC)** | The web component, which directly owns lifecycle, prop normalization, state management, Behavior composition and rendering. |\n| **Functional Component** | Pure renderer without side effects that exclusively works with Props. |\n| **Props** | Normalized and validated props or internal state passed to functional components. Must always be initialized. |\n| **Render props** | Validated, normalized prop values stored on the WC via `setRenderProp` and read via `getRenderProp` for rendering. |\n| **Schema Helper** | Utility providing `normalize` (unknown → TInternal), `validate` (TInternal → boolean) and `apply` (normalize + validate + callback) for props. |\n| **Schema Type** | Named value type of one prop in `src/schema/props` (e.g. `DisabledPropType`); the single spelling every layer references. |\n| **StateAccess** | `{ setState, getState }` bundle a WC passes to a Behavior; `BaseWebComponent.stateLess` is the no-op sentinel for stateless Behaviors. |\n| **Stencil** | Compiler for building framework-agnostic web components. |\n| **Transitional WC** | A `shadow:false` WC that renders an FC into the light DOM so legacy consumers can reach inner BEM classes; deleted once consumers migrate. |\n| **Watch Decorator** | Stencil decorator (`@Watch`) that observes prop changes. |\n",
3649
3681
  "kind": "spec"
3650
3682
  },
3651
3683
  {
@@ -3663,7 +3695,7 @@
3663
3695
  "name": "badge",
3664
3696
  "description": "The Badge component allows you to visually highlight specific information. In addition to specifying the background color and automatically calculating the text color, it also supports adding an icon and/or a different font style.",
3665
3697
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/badge.md",
3666
- "code": "# kol-badge\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Badge** component allows you to visually highlight specific information.\nIn addition to specifying the background color and automatically calculating the text color, it also supports adding an icon and/or a different font style.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_color` | `_color` | Defines the backgroundColor and foregroundColor. | `string \\| undefined \\| { backgroundColor: string; foregroundColor: string; }` | `'#000'` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3698
+ "code": "# kol-badge\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Badge** component allows you to visually highlight specific information.\nIn addition to specifying the background color and automatically calculating the text color, it also supports adding an icon and/or a different font style.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_color` | `_color` | Defines the backgroundColor and foregroundColor. | `string \\| undefined \\| { backgroundColor: string; foregroundColor: string; }` | `'#000'` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| 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| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3667
3699
  "kind": "spec"
3668
3700
  },
3669
3701
  {
@@ -3672,7 +3704,7 @@
3672
3704
  "name": "breadcrumb",
3673
3705
  "description": "The Breadcrumb component can be used to display the path to the current position of a web page within a hierarchical structure.",
3674
3706
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/breadcrumb.md",
3675
- "code": "# kol-breadcrumb\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Breadcrumb** component can be used to display the path to the current position of a web page within a hierarchical structure.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_links` _(required)_ | `_links` | Defines the list of links combined with their labels to render. | `BreadcrumbLinkProps[] \\| string` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3707
+ "code": "# kol-breadcrumb\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Breadcrumb** component can be used to display the path to the current position of a web page within a hierarchical structure.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_links` _(required)_ | `_links` | Defines the list of links combined with their labels to render. | `LinkProps[] \\| string` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3676
3708
  "kind": "spec"
3677
3709
  },
3678
3710
  {
@@ -3681,7 +3713,7 @@
3681
3713
  "name": "button",
3682
3714
  "description": "The Button component is used to present users with action options and arrange them in a clear hierarchy. It helps users find the most important actions on a page or within a viewport and allows them to execute those actions. The button label clearly indicates which action will be triggered. Buttons…",
3683
3715
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/button.md",
3684
- "code": "# kol-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Button** component is used to present users with action options and arrange them in a clear hierarchy. It helps users find the most important actions on a page or within a viewport and allows them to execute those actions. The button label clearly indicates which action will be triggered. Buttons allow users to confirm a change, complete steps in a task, or make decisions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3716
+ "code": "# kol-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Button** component is used to present users with action options and arrange them in a clear hierarchy. It helps users find the most important actions on a page or within a viewport and allows them to execute those actions. The button label clearly indicates which action will be triggered. Buttons allow users to confirm a change, complete steps in a task, or make decisions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3685
3717
  "kind": "spec"
3686
3718
  },
3687
3719
  {
@@ -3690,7 +3722,7 @@
3690
3722
  "name": "button-link",
3691
3723
  "description": "The ButtonLink component is semantically a button but has the appearance of a link. All relevant properties of the Button component are adopted and extended with the design-defining properties of a link.",
3692
3724
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/button-link.md",
3693
- "code": "# kol-button-link\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **ButtonLink** component is semantically a button but has the appearance of a link. All relevant properties of the Button component are adopted and extended with the design-defining properties of a link.\n\nA button can be disabled, therefore the **ButtonLink** also has the `_disabled` property. How this is styled visually is determined by the UX designer.\n\nInstead of using `_href` as with a regular link, the **ButtonLink**'s behavior is controlled via a click callback using the `_on` property.\n\nA link has the `target` property which optionally opens the link in a new window/tab. This behavior is not yet implemented.\n\nSince a link, unlike a button, is not offered in multiple variants (`primary`, `secondary`, etc.), the `_customClass` and `_variant` properties are not available.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `true` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. |\n\n\n----------------------------------------------\n\n\n",
3725
+ "code": "# kol-button-link\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **ButtonLink** component is semantically a button but has the appearance of a link. All relevant properties of the Button component are adopted and extended with the design-defining properties of a link.\n\nA button can be disabled, therefore the **ButtonLink** also has the `_disabled` property. How this is styled visually is determined by the UX designer.\n\nInstead of using `_href` as with a regular link, the **ButtonLink**'s behavior is controlled via a click callback using the `_on` property.\n\nA link has the `target` property which optionally opens the link in a new window/tab. This behavior is not yet implemented.\n\nSince a link, unlike a button, is not offered in multiple variants (`primary`, `secondary`, etc.), the `_variant` property only accepts custom class names here and the `_customClass` property is not available.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `true` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. |\n\n\n----------------------------------------------\n\n\n",
3694
3726
  "kind": "spec"
3695
3727
  },
3696
3728
  {
@@ -3699,7 +3731,7 @@
3699
3731
  "name": "card",
3700
3732
  "description": "The Card component is ideal for visually highlighting individual sections of your website. It allows you to structure your content very easily.",
3701
3733
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/card.md",
3702
- "code": "# kol-card\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Card** component is ideal for visually highlighting individual sections of your website. It allows you to structure your content very easily.\n\nThe **Card** component consists of a **_title area_** and a **_content area_**.\n\nThe **title area** is displayed in a larger font. The **content area** is visually separated from the title area by a horizontal dividing line and is rendered in the default font.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\n| `_href` | `_href` | Sets the target URI of the link or citation source. | `string \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the event callback functions for the component. | `undefined \\| { onClose?: EventCallback<Event> \\| undefined; onFocus?: EventCallback<FocusEvent> \\| undefined; onBlur?: EventCallback<FocusEvent> \\| undefined; }` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the content area of the card. |\n\n\n----------------------------------------------\n\n\n",
3734
+ "code": "# kol-card\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Card** component is ideal for visually highlighting individual sections of your website. It allows you to structure your content very easily.\n\nThe **Card** component consists of a **_title area_** and a **_content area_**.\n\nThe **title area** is displayed in a larger font. The **content area** is visually separated from the title area by a horizontal dividing line and is rendered in the default font.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\n| `_href` | `_href` | Defines the target URI of the link. | `string \\| 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| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the event callback functions for the component. | `undefined \\| { onClose?: EventCallback<Event> \\| undefined; onFocus?: EventCallback<FocusEvent> \\| undefined; onBlur?: EventCallback<FocusEvent> \\| undefined; }` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the content area of the card. |\n\n\n----------------------------------------------\n\n\n",
3703
3735
  "kind": "spec"
3704
3736
  },
3705
3737
  {
@@ -3708,7 +3740,7 @@
3708
3740
  "name": "combobox",
3709
3741
  "description": "Clicks the primary interactive element inside this component.",
3710
3742
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/combobox.md",
3711
- "code": "# kol-combobox\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this combobox. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasClearButton` | `_has-clear-button` | Shows the clear button if enabled. | `boolean \\| undefined` | `true` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_suggestions` _(required)_ | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3743
+ "code": "# kol-combobox\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this combobox. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasClearButton` | `_has-clear-button` | Shows the clear button if enabled. | `boolean \\| undefined` | `true` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_suggestions` _(required)_ | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3712
3744
  "kind": "spec"
3713
3745
  },
3714
3746
  {
@@ -3726,7 +3758,7 @@
3726
3758
  "name": "details",
3727
3759
  "description": "The Details component allows additional information to be initially shown with a short introductory text, which is only fully expanded after the user clicks on an arrow icon.",
3728
3760
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/details.md",
3729
- "code": "# kol-details\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Details** component allows additional information to be initially shown with a short introductory text,\nwhich is only fully expanded after the user clicks on an arrow icon.\n\nBy default, the **Details** component is displayed as a single-line layout element consisting of an arrow icon\nfollowed by a short introductory text. The actual content is revealed below after clicking the header area. The arrow icon\nchanges its orientation from **_right_** to **_down_**.\nThe component can also be closed again to hide the content.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------- |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the callback functions for the collapsible. | `boolean \\| undefined` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nTriggers a click on the heading toggle button.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------------------------ |\n| | The content displayed in the detail description. |\n\n\n----------------------------------------------\n\n\n",
3761
+ "code": "# kol-details\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Details** component allows additional information to be initially shown with a short introductory text,\nwhich is only fully expanded after the user clicks on an arrow icon.\n\nBy default, the **Details** component is displayed as a single-line layout element consisting of an arrow icon\nfollowed by a short introductory text. The actual content is revealed below after clicking the header area. The arrow icon\nchanges its orientation from **_right_** to **_down_**.\nThe component can also be closed again to hide the content.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------- |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\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| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the callback functions for the collapsible. | `boolean \\| undefined` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nTriggers a click on the heading toggle button.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------------------------ |\n| | The content displayed in the detail description. |\n\n\n----------------------------------------------\n\n\n",
3730
3762
  "kind": "spec"
3731
3763
  },
3732
3764
  {
@@ -3735,7 +3767,7 @@
3735
3767
  "name": "dialog",
3736
3768
  "description": "Opens the dialog. Pass true to open as a modal dialog.",
3737
3769
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/dialog.md",
3738
- "code": "# kol-dialog\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the modal callback functions. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines the variant of the modal. | `\"blank\" \\| \"card\" \\| undefined` | `'blank'` |\n| `_width` | `_width` | Defines the width of the modal. (max-width: 100%) | `string \\| undefined` | `'100%'` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closeModal() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use close() instead.<br/><br/>Closes the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `openModal() => Promise<void>`\n\n<span style=\"color:red\">**[DEPRECATED]**</span> Use showModal() instead.<br/><br/>Opens the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the dialog. Pass true to open as a modal dialog.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the dialog as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------- |\n| | The dialog's contents. |\n\n\n----------------------------------------------\n\n\n",
3770
+ "code": "# kol-dialog\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\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| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Defines the modal callback functions. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines the variant of the modal. | `\"blank\" \\| \"card\" \\| undefined` | `'blank'` |\n| `_width` | `_width` | Defines the width of the modal. (max-width: 100%) | `string \\| undefined` | `'100%'` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closeModal() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use close() instead.<br/><br/>Closes the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `openModal() => Promise<void>`\n\n<span style=\"color:red\">**[DEPRECATED]**</span> Use showModal() instead.<br/><br/>Opens the dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the dialog. Pass true to open as a modal dialog.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the dialog as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------- |\n| | The dialog's contents. |\n\n\n----------------------------------------------\n\n\n",
3739
3771
  "kind": "spec"
3740
3772
  },
3741
3773
  {
@@ -3744,7 +3776,7 @@
3744
3776
  "name": "drawer",
3745
3777
  "description": "Opens the drawer. Pass true to open as a modal drawer.",
3746
3778
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/drawer.md",
3747
- "code": "# kol-drawer\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_align` | `_align` | Defines the visual orientation of the component. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `undefined` |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Specifies the EventCallback function to be called when the drawer is closing. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the drawer.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `open() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use show() or showModal() instead.<br/><br/>Opens the drawer.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the drawer. Pass true to open as a modal drawer.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the drawer as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------- |\n| | The Content of drawer. |\n\n\n----------------------------------------------\n\n\n",
3779
+ "code": "# kol-drawer\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_align` | `_align` | Defines the visual orientation of the component. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `undefined` |\n| `_hasCloser` | `_has-closer` | Defines whether the element can be closed. | `boolean \\| undefined` | `false` |\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| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_on` | -- | Specifies the EventCallback function to be called when the drawer is closing. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the drawer.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `open() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use show() or showModal() instead.<br/><br/>Opens the drawer.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the drawer. Pass true to open as a modal drawer.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the drawer as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ---------------------- |\n| | The Content of drawer. |\n\n\n----------------------------------------------\n\n\n",
3748
3780
  "kind": "spec"
3749
3781
  },
3750
3782
  {
@@ -3761,7 +3793,7 @@
3761
3793
  "group": "spec",
3762
3794
  "name": "heading",
3763
3795
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/heading.md",
3764
- "code": "# kol-heading\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_secondaryHeadline` | `_secondary-headline` | Defines the text of the secondary headline. | `string \\| undefined` | `undefined` |\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3796
+ "code": "# kol-heading\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_level` | `_level` | Defines which H-level from 1-6 the heading has. 0 specifies no heading and is shown as bold text. | `0 \\| 1 \\| 2 \\| 3 \\| 4 \\| 5 \\| 6 \\| undefined` | `0` |\n| `_secondaryHeadline` | `_secondary-headline` | Defines the text of the secondary headline. | `string \\| undefined` | `undefined` |\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3765
3797
  "kind": "spec"
3766
3798
  },
3767
3799
  {
@@ -3788,7 +3820,7 @@
3788
3820
  "name": "input-checkbox",
3789
3821
  "description": "The Checkbox input type generates a rectangular box that can be activated and deactivated by clicking. When activated, a colored checkmark is shown inside the box.",
3790
3822
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-checkbox.md",
3791
- "code": "# kol-input-checkbox\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Checkbox** input type generates a rectangular box that can be activated and deactivated by clicking. When activated, a colored checkmark is shown inside the box.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_checked` | `_checked` | Defines whether the checkbox is checked or not. Can be read and written. | `boolean \\| undefined` | `false` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { checked: string; indeterminate?: string \\| undefined; unchecked?: string \\| undefined; } \\| { checked?: string \\| undefined; indeterminate: string; unchecked?: string \\| undefined; } \\| { checked?: string \\| undefined; indeterminate?: string \\| undefined; unchecked: string; }` | `undefined` |\n| `_indeterminate` | `_indeterminate` | Puts the checkbox in the indeterminate state, does not change the value of _checked. | `boolean \\| undefined` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_labelAlign` | `_label-align` | Defines which alignment should be used for presentation. | `\"left\" \\| \"right\" \\| undefined` | `'right'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `true` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"button\" \\| \"default\" \\| \"switch\" \\| undefined` | `'default'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3823
+ "code": "# kol-input-checkbox\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Checkbox** input type generates a rectangular box that can be activated and deactivated by clicking. When activated, a colored checkmark is shown inside the box.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_checked` | `_checked` | Defines whether the checkbox is checked or not. Can be read and written. | `boolean \\| undefined` | `false` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { checked: string; indeterminate?: string \\| undefined; unchecked?: string \\| undefined; } \\| { checked?: string \\| undefined; indeterminate: string; unchecked?: string \\| undefined; } \\| { checked?: string \\| undefined; indeterminate?: string \\| undefined; unchecked: string; }` | `undefined` |\n| `_indeterminate` | `_indeterminate` | Puts the checkbox in the indeterminate state, does not change the value of _checked. | `boolean \\| undefined` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_labelAlign` | `_label-align` | Defines which alignment should be used for presentation. | `\"left\" \\| \"right\" \\| undefined` | `'right'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `true` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"button\" \\| \"default\" \\| \"switch\" \\| undefined` | `'default'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3792
3824
  "kind": "spec"
3793
3825
  },
3794
3826
  {
@@ -3797,7 +3829,7 @@
3797
3829
  "name": "input-color",
3798
3830
  "description": "The Color input type creates a selection field for defining any color. The color can be entered in hexadecimal, RGB, or HSL notation. It is possible to select a color via a picker or by entering exact color values.",
3799
3831
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-color.md",
3800
- "code": "# kol-input-color\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Color** input type creates a selection field for defining any color. The color can be entered in hexadecimal, RGB, or HSL notation. It is possible to select a color via a picker or by entering exact color values.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3832
+ "code": "# kol-input-color\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Color** input type creates a selection field for defining any color. The color can be entered in hexadecimal, RGB, or HSL notation. It is possible to select a color via a picker or by entering exact color values.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3801
3833
  "kind": "spec"
3802
3834
  },
3803
3835
  {
@@ -3806,7 +3838,7 @@
3806
3838
  "name": "input-date",
3807
3839
  "description": "The Date input type creates an input field for date values. These can be specific dates as well as weeks, months, or time values.",
3808
3840
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-date.md",
3809
- "code": "# kol-input-date\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Date** input type creates an input field for date values. These can be specific dates as well as weeks, months, or time values.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| undefined `` | `undefined` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| undefined `` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"date\" \\| \"datetime-local\" \\| \"month\" \\| \"time\" \\| \"week\"` | `'date'` |\n| `_value` | `_value` | Defines the value of the element. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| null \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | Date | undefined | null>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | Date | null | undefined>`\n\n\n\n### `reset() => Promise<void>`\n\nResets the component's value.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3841
+ "code": "# kol-input-date\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Date** input type creates an input field for date values. These can be specific dates as well as weeks, months, or time values.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| undefined `` | `undefined` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| undefined `` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"date\" \\| \"datetime-local\" \\| \"month\" \\| \"time\" \\| \"week\"` | `'date'` |\n| `_value` | `_value` | Defines the value of the element. | `` Date \\| `${number}-${number}-${number}T${number}:${number}:${number}` \\| `${number}-${number}-${number}T${number}:${number}` \\| `${number}-${number}-${number}` \\| `${number}-${number}` \\| `${number}-W${number}` \\| `${number}:${number}:${number}` \\| `${number}:${number}` \\| null \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | Date | undefined | null>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | Date | null | undefined>`\n\n\n\n### `reset() => Promise<void>`\n\nResets the component's value.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3810
3842
  "kind": "spec"
3811
3843
  },
3812
3844
  {
@@ -3815,7 +3847,7 @@
3815
3847
  "name": "input-email",
3816
3848
  "description": "The Email input type creates an input field for email addresses. It supports built-in format validation, multiple addresses via the _multiple property, and auto-complete suggestions.",
3817
3849
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-email.md",
3818
- "code": "# kol-input-email\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Email** input type creates an input field for email addresses. It supports built-in format validation, multiple addresses via the `_multiple` property, and auto-complete suggestions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3850
+ "code": "# kol-input-email\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Email** input type creates an input field for email addresses. It supports built-in format validation, multiple addresses via the `_multiple` property, and auto-complete suggestions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3819
3851
  "kind": "spec"
3820
3852
  },
3821
3853
  {
@@ -3824,7 +3856,7 @@
3824
3856
  "name": "input-file",
3825
3857
  "description": "The File input type creates an input field for file uploads. One or multiple files can be selected and submitted with a form.",
3826
3858
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-file.md",
3827
- "code": "# kol-input-file\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **File** input type creates an input field for file uploads. One or multiple files can be selected and submitted with a form.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accept` | `_accept` | Defines which file formats are accepted. | `string \\| undefined` | `undefined` |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<FileList | null | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<FileList | null | undefined>`\n\n\n\n### `reset() => Promise<void>`\n\nResets the component's value.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3859
+ "code": "# kol-input-file\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **File** input type creates an input field for file uploads. One or multiple files can be selected and submitted with a form.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accept` | `_accept` | Defines which file formats are accepted. | `string \\| undefined` | `undefined` |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<FileList | null | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<FileList | null | undefined>`\n\n\n\n### `reset() => Promise<void>`\n\nResets the component's value.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3828
3860
  "kind": "spec"
3829
3861
  },
3830
3862
  {
@@ -3833,7 +3865,7 @@
3833
3865
  "name": "input-number",
3834
3866
  "description": "The Number input type creates an input field for numeric values. Use the _min, _max, and _step properties to restrict the accepted value range.",
3835
3867
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-number.md",
3836
- "code": "# kol-input-number\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Number** input type creates an input field for numeric values. Use the `_min`, `_max`, and `_step` properties to restrict the accepted value range.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `` `${number}.${number}` \\| `${number}` \\| null \\| number \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<number | NumberString | null>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<number | NumberString | null>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3868
+ "code": "# kol-input-number\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Number** input type creates an input field for numeric values. Use the `_min`, `_max`, and `_step` properties to restrict the accepted value range.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `` `${number}.${number}` \\| `${number}` \\| null \\| number \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<number | NumberString | null>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<number | NumberString | null>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3837
3869
  "kind": "spec"
3838
3870
  },
3839
3871
  {
@@ -3842,7 +3874,7 @@
3842
3874
  "name": "input-password",
3843
3875
  "description": "The Password input type creates an input field for passwords. The input is masked with dot symbols.",
3844
3876
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-password.md",
3845
- "code": "# kol-input-password\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Password** input type creates an input field for passwords. The input is masked with dot symbols.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n| `_visibilityToggle` | `_visibility-toggle` | Activates the show password button | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3877
+ "code": "# kol-input-password\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Password** input type creates an input field for passwords. The input is masked with dot symbols.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n| `_visibilityToggle` | `_visibility-toggle` | Activates the show password button | `boolean \\| undefined` | `false` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3846
3878
  "kind": "spec"
3847
3879
  },
3848
3880
  {
@@ -3851,7 +3883,7 @@
3851
3883
  "name": "input-radio",
3852
3884
  "description": "The InputRadio input type consists of a collection of radio elements, providing a choice between different values. Only a single value can be selected at a time. Selected radio elements are typically represented by a filled, visually highlighted circle.",
3853
3885
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-radio.md",
3854
- "code": "# kol-input-radio\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **InputRadio** input type consists of a collection of radio elements, providing a choice between different values. Only a single value can be selected at a time. Selected radio elements are typically represented by a filled, visually highlighted circle.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` | `_options` | Options the user can choose from. | `RadioOption<StencilUnknown>[] \\| string \\| undefined` | `undefined` |\n| `_orientation` | `_orientation` | Defines whether the orientation of the component is horizontal or vertical. | `\"horizontal\" \\| \"vertical\" \\| undefined` | `'vertical'` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `null` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3886
+ "code": "# kol-input-radio\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **InputRadio** input type consists of a collection of radio elements, providing a choice between different values. Only a single value can be selected at a time. Selected radio elements are typically represented by a filled, visually highlighted circle.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` | `_options` | Options the user can choose from. | `RadioOption<StencilUnknown>[] \\| string \\| undefined` | `undefined` |\n| `_orientation` | `_orientation` | Defines whether the orientation of the component is horizontal or vertical. | `\"horizontal\" \\| \"vertical\" \\| undefined` | `'vertical'` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `null` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3855
3887
  "kind": "spec"
3856
3888
  },
3857
3889
  {
@@ -3860,7 +3892,7 @@
3860
3892
  "name": "input-range",
3861
3893
  "description": "The Range input type creates a slider control for selecting a numeric value within a defined range. Use the _min, _max, and _step properties to configure the range and step size.",
3862
3894
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-range.md",
3863
- "code": "# kol-input-range\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Range** input type creates a slider control for selecting a numeric value within a defined range. Use the `_min`, `_max`, and `_step` properties to configure the range and step size.\n\nLike a native range input, the field always has a value: without `_value` it starts at the middle of the range and reports it as its value and form value.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `100` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `0` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<number | NumberString | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<number | NumberString | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3895
+ "code": "# kol-input-range\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Range** input type creates a slider control for selecting a numeric value within a defined range. Use the `_min`, `_max`, and `_step` properties to configure the range and step size.\n\nLike a native range input, the field always has a value: without `_value` it starts at the middle of the range and reports it as its value and form value.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `100` |\n| `_min` | `_min` | Defines the smallest possible input value. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `0` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_step` | `_step` | Defines the step size for value changes. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `` `${number}.${number}` \\| `${number}` \\| number \\| undefined `` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<number | NumberString | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<number | NumberString | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3864
3896
  "kind": "spec"
3865
3897
  },
3866
3898
  {
@@ -3869,7 +3901,7 @@
3869
3901
  "name": "input-text",
3870
3902
  "description": "The Text input type creates an input field for plain text, search terms, URLs, or phone numbers.",
3871
3903
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/input-text.md",
3872
- "code": "# kol-input-text\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Text** input type creates an input field for plain text, search terms, URLs, or phone numbers.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: string; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_spellCheck` | `_spell-check` | Defines whether the browser should check the spelling and grammar. | `boolean \\| undefined` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"search\" \\| \"tel\" \\| \"text\" \\| \"url\" \\| undefined` | `'text'` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n### `selectionEnd() => Promise<number | null | undefined>`\n\nGet selection end of internal element.\n\n#### Returns\n\nType: `Promise<number | null | undefined>`\n\n\n\n### `selectionStart() => Promise<number | null | undefined>`\n\nGet selection start of internal element.\n\n#### Returns\n\nType: `Promise<number | null | undefined>`\n\n\n\n### `setRangeText(replacement: string, selectionStart?: number, selectionEnd?: number, selectMode?: \"select\" | \"start\" | \"end\" | \"preserve\") => Promise<void>`\n\nAdd string at position of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setRangeText\n\n#### Parameters\n\n| Name | Type | Description |\n| ---------------- | --------------------------------------------------------- | ----------- |\n| `replacement` | `string` | |\n| `selectionStart` | `number \\| undefined` | |\n| `selectionEnd` | `number \\| undefined` | |\n| `selectMode` | `\"select\" \\| \"end\" \\| \"start\" \\| \"preserve\" \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: \"forward\" | \"backward\" | \"none\") => Promise<void>`\n\nSet selection start and end, and optional in which direction, of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setSelectionRange\n\n#### Parameters\n\n| Name | Type | Description |\n| -------------------- | ------------------------------------------------ | ----------- |\n| `selectionStart` | `number` | |\n| `selectionEnd` | `number` | |\n| `selectionDirection` | `\"none\" \\| \"forward\" \\| \"backward\" \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `setSelectionStart(selectionStart: number) => Promise<void>`\n\nSet selection start (and end = start) of internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| ---------------- | -------- | ----------- |\n| `selectionStart` | `number` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3904
+ "code": "# kol-input-text\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Text** input type creates an input field for plain text, search terms, URLs, or phone numbers.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_autoComplete` | `_auto-complete` | Defines whether the input can be auto-completed. | `string \\| undefined` | `'off'` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_pattern` | `_pattern` | Defines a validation pattern for the input field. | `string \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_smartButton` | `_smart-button` | Allows to add a button with an arbitrary action within the element (_hide-label only). | `string \\| undefined \\| { _label: LabelWithExpertSlotPropType; } & { _ariaExpanded?: boolean \\| undefined; _tabIndex?: number \\| undefined; _value?: StencilUnknown; _accessKey?: string \\| undefined; _role?: \"tab\" \\| \"treeitem\" \\| undefined; _ariaControls?: string \\| undefined; _ariaDescription?: string \\| undefined; _ariaSelected?: boolean \\| undefined; _on?: ButtonCallbacksPropType<StencilUnknown> \\| undefined; _type?: \"button\" \\| \"reset\" \\| \"submit\" \\| undefined; _variant?: VariantClassNamePropType \\| undefined; _customClass?: string \\| undefined; _disabled?: boolean \\| undefined; _hideLabel?: boolean \\| undefined; _icons?: IconsPropType \\| undefined; _id?: string \\| undefined; _inline?: boolean \\| undefined; _name?: string \\| undefined; _shortKey?: string \\| undefined; _syncValueBySelector?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_spellCheck` | `_spell-check` | Defines whether the browser should check the spelling and grammar. | `boolean \\| undefined` | `undefined` |\n| `_suggestions` | `_suggestions` | Suggestions to provide for the input. | `W3CInputValue[] \\| string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"search\" \\| \"tel\" \\| \"text\" \\| \"url\" \\| undefined` | `'text'` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n### `selectionEnd() => Promise<number | null | undefined>`\n\nGet selection end of internal element.\n\n#### Returns\n\nType: `Promise<number | null | undefined>`\n\n\n\n### `selectionStart() => Promise<number | null | undefined>`\n\nGet selection start of internal element.\n\n#### Returns\n\nType: `Promise<number | null | undefined>`\n\n\n\n### `setRangeText(replacement: string, selectionStart?: number, selectionEnd?: number, selectMode?: \"select\" | \"start\" | \"end\" | \"preserve\") => Promise<void>`\n\nAdd string at position of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setRangeText\n\n#### Parameters\n\n| Name | Type | Description |\n| ---------------- | --------------------------------------------------------- | ----------- |\n| `replacement` | `string` | |\n| `selectionStart` | `number \\| undefined` | |\n| `selectionEnd` | `number \\| undefined` | |\n| `selectMode` | `\"select\" \\| \"end\" \\| \"start\" \\| \"preserve\" \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `setSelectionRange(selectionStart: number, selectionEnd: number, selectionDirection?: \"forward\" | \"backward\" | \"none\") => Promise<void>`\n\nSet selection start and end, and optional in which direction, of internal element; just like https://developer.mozilla.org/docs/Web/API/HTMLInputElement/setSelectionRange\n\n#### Parameters\n\n| Name | Type | Description |\n| -------------------- | ------------------------------------------------ | ----------- |\n| `selectionStart` | `number` | |\n| `selectionEnd` | `number` | |\n| `selectionDirection` | `\"none\" \\| \"forward\" \\| \"backward\" \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `setSelectionStart(selectionStart: number) => Promise<void>`\n\nSet selection start (and end = start) of internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| ---------------- | -------- | ----------- |\n| `selectionStart` | `number` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| | The label of the input field. |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3873
3905
  "kind": "spec"
3874
3906
  },
3875
3907
  {
@@ -3886,7 +3918,7 @@
3886
3918
  "name": "link",
3887
3919
  "description": "Sets focus on the internal element.",
3888
3920
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/link.md",
3889
- "code": "# kol-link\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaCurrentValue` | `_aria-current-value` | Defines the value for the aria-current attribute. | `\"date\" \\| \"false\" \\| \"location\" \\| \"page\" \\| \"step\" \\| \"time\" \\| \"true\" \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_download` | `_download` | Tells the browser that the link contains a file. Optionally sets the filename. | `string \\| undefined` | `undefined` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_href` _(required)_ | `_href` | Sets the target URI of the link or citation source. | `string` | `undefined` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `true` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for links. | `undefined \\| { onClick?: EventValueOrEventCallback<Event, string> \\| undefined; }` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'right'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3921
+ "code": "# kol-link\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaCurrentValue` | `_aria-current-value` | Defines the value for the aria-current attribute. | `\"date\" \\| \"false\" \\| \"location\" \\| \"page\" \\| \"step\" \\| \"time\" \\| \"true\" \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_download` | `_download` | Tells the browser that the link contains a file. Optionally sets the filename. | `string \\| undefined` | `undefined` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `undefined` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `true` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for links. | `undefined \\| { onClick?: EventValueOrEventCallback<Event, string> \\| undefined; }` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'right'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: FocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | --------------------------- | ----------- |\n| `options` | `FocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3890
3922
  "kind": "spec"
3891
3923
  },
3892
3924
  {
@@ -3895,7 +3927,7 @@
3895
3927
  "name": "link-button",
3896
3928
  "description": "The LinkButton component is semantically a link but has the appearance of a button. All relevant properties of the Link component are adopted and extended with the design-defining properties of a button.",
3897
3929
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/link-button.md",
3898
- "code": "# kol-link-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **LinkButton** component is semantically a link but has the appearance of a button. All relevant properties of the Link component are adopted and extended with the design-defining properties of a button.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaCurrentValue` | `_aria-current-value` | Defines the value for the aria-current attribute. | `\"date\" \\| \"false\" \\| \"location\" \\| \"page\" \\| \"step\" \\| \"time\" \\| \"true\" \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_download` | `_download` | Tells the browser that the link contains a file. Optionally sets the filename. | `string \\| undefined` | `undefined` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `undefined` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for links. | `undefined \\| { onClick?: EventValueOrEventCallback<Event, string> \\| undefined; }` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'right'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `getFeatureFlag('buttonVariantDefault', this.host) ?? 'normal'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. |\n\n\n----------------------------------------------\n\n\n",
3930
+ "code": "# kol-link-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **LinkButton** component is semantically a link but has the appearance of a button. All relevant properties of the Link component are adopted and extended with the design-defining properties of a button.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaCurrentValue` | `_aria-current-value` | Defines the value for the aria-current attribute. | `\"date\" \\| \"false\" \\| \"location\" \\| \"page\" \\| \"step\" \\| \"time\" \\| \"true\" \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_download` | `_download` | Tells the browser that the link contains a file. Optionally sets the filename. | `string \\| undefined` | `undefined` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `undefined` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for links. | `undefined \\| { onClick?: EventValueOrEventCallback<Event, string> \\| undefined; }` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_target` | `_target` | Defines where to open the link. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'right'` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `getFeatureFlag('buttonVariantDefault', this.host) ?? 'normal'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: FocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | --------------------------- | ----------- |\n| `options` | `FocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. |\n\n\n----------------------------------------------\n\n\n",
3899
3931
  "kind": "spec"
3900
3932
  },
3901
3933
  {
@@ -3903,7 +3935,7 @@
3903
3935
  "group": "spec",
3904
3936
  "name": "meter",
3905
3937
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/meter.md",
3906
- "code": "# kol-meter\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- |\n| `_high` | `_high` | From this value to the max value is the high range of the meter. Below this value is the middle range. | `number \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_low` | `_low` | From this value to the min value is the low range of the meter. Above this value is the middle range. | `number \\| undefined` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. Default like native component. | `number` | `1` |\n| `_min` | `_min` | Defines the minimum value of the element. Default like native component. | `number` | `0` |\n| `_optimum` | `_optimum` | Indicates the optimal range of the element. If this lies in the high range, the high range will be optimum, the middle range will be suboptimum and the low range will be critical. If this lies in the low range, the low range will be optimum, the middle range will be suboptimum and the high range will be critical. If this lies in the middle range, both low and high range will be suboptimum and nothing will be critical. | `number \\| undefined` | `undefined` |\n| `_orientation` | `_orientation` | Defines whether the meter bar is displayed horizontally or vertically. | `\"horizontal\" \\| \"vertical\"` | `'horizontal'` |\n| `_unit` | `_unit` | Defines the unit of the value. | `string` | `'%'` |\n| `_value` _(required)_ | `_value` | Defines the value of the element. Is capped between min and max. | `number` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3938
+ "code": "# kol-meter\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------------- |\n| `_high` | `_high` | From this value to the max value is the high range of the meter. Below this value is the middle range. | `number \\| 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| `_low` | `_low` | From this value to the min value is the low range of the meter. Above this value is the middle range. | `number \\| undefined` | `undefined` |\n| `_max` | `_max` | Defines the maximum value of the element. Default like native component. | `number` | `1` |\n| `_min` | `_min` | Defines the minimum value of the element. Default like native component. | `number` | `0` |\n| `_optimum` | `_optimum` | Indicates the optimal range of the element. If this lies in the high range, the high range will be optimum, the middle range will be suboptimum and the low range will be critical. If this lies in the low range, the low range will be optimum, the middle range will be suboptimum and the high range will be critical. If this lies in the middle range, both low and high range will be suboptimum and nothing will be critical. | `number \\| undefined` | `undefined` |\n| `_orientation` | `_orientation` | Defines whether the meter bar is displayed horizontally or vertically. | `\"horizontal\" \\| \"vertical\"` | `'horizontal'` |\n| `_unit` | `_unit` | Defines the unit of the value. | `string` | `'%'` |\n| `_value` _(required)_ | `_value` | Defines the value of the element. Is capped between min and max. | `number` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3907
3939
  "kind": "spec"
3908
3940
  },
3909
3941
  {
@@ -3912,7 +3944,7 @@
3912
3944
  "name": "modal",
3913
3945
  "description": "The Modal component has been superseded by kol-dialog, which provides improved accessibility and conforms to the HTML dialog specification. It is still available in version 2 for backwards compatibility.",
3914
3946
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/modal.md",
3915
- "code": "# kol-modal\n\n\n\n<!-- Auto Generated Below -->\n\n\n> **[DEPRECATED]** Use `kol-dialog` instead.\n\n## Overview\n\nThe **Modal** component has been superseded by `kol-dialog`, which provides improved accessibility and conforms to the HTML dialog specification. It is still available in version 2 for backwards compatibility.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_on` | -- | Defines the modal callback functions. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines the variant of the modal. | `\"blank\" \\| \"card\" \\| undefined` | `'blank'` |\n| `_width` | `_width` | Defines the width of the modal. (max-width: 100%) | `string \\| undefined` | `'100%'` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closeModal() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use close() instead.<br/><br/>Closes the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `openModal() => Promise<void>`\n\n<span style=\"color:red\">**[DEPRECATED]**</span> Use showModal() instead.<br/><br/>Opens the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the dialog. Pass true to open as a modal dialog.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the dialog as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | --------------------- |\n| | The modal's contents. |\n\n\n----------------------------------------------\n\n\n",
3947
+ "code": "# kol-modal\n\n\n\n<!-- Auto Generated Below -->\n\n\n> **[DEPRECATED]** Use `kol-dialog` instead.\n\n## Overview\n\nThe **Modal** component has been superseded by `kol-dialog`, which provides improved accessibility and conforms to the HTML dialog specification. It is still available in version 2 for backwards compatibility.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\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| `_on` | -- | Defines the modal callback functions. | `undefined \\| ({ onCancel?: ((event: Event) => void) \\| undefined; onClose?: (() => void) \\| undefined; onToggle?: ((open: boolean) => void) \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines the variant of the modal. | `\"blank\" \\| \"card\" \\| undefined` | `'blank'` |\n| `_width` | `_width` | Defines the width of the modal. (max-width: 100%) | `string \\| undefined` | `'100%'` |\n\n\n## Methods\n\n### `close() => Promise<void>`\n\nCloses the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closeModal() => Promise<void>`\n\n<span class=\"text-red-500\">**[DEPRECATED]**</span> Use close() instead.<br/><br/>Closes the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `openModal() => Promise<void>`\n\n<span style=\"color:red\">**[DEPRECATED]**</span> Use showModal() instead.<br/><br/>Opens the modal dialog.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `show(modal?: boolean) => Promise<void>`\n\nOpens the dialog. Pass true to open as a modal dialog.\n\n#### Parameters\n\n| Name | Type | Description |\n| ------- | --------- | ----------- |\n| `modal` | `boolean` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showModal() => Promise<void>`\n\nOpens the dialog as a modal.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | --------------------- |\n| | The modal's contents. |\n\n\n----------------------------------------------\n\n\n",
3916
3948
  "kind": "spec"
3917
3949
  },
3918
3950
  {
@@ -3938,7 +3970,7 @@
3938
3970
  "name": "popover-button",
3939
3971
  "description": "A button that toggles the visibility of a popover overlay containing arbitrary content. The popover uses the native HTML Popover API for lightweight, non-modal overlays.",
3940
3972
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/popover-button.md",
3941
- "code": "# kol-popover-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nA button that toggles the visibility of a popover overlay containing arbitrary content.\nThe popover uses the native HTML Popover API for lightweight, non-modal overlays.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_popoverAlign` | `_popover-align` | Defines where to show the Popover preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tabIndex` | `_tab-index` | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `hidePopover() => Promise<void>`\n\nHides the popover programmatically.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showPopover() => Promise<void>`\n\nShows the popover programmatically.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | --------------------------------------------------------------- |\n| | The popover content (displayed when the button is clicked). |\n| `\"expert\"` | Custom label content for the button (when `_label` is `false`). |\n\n\n----------------------------------------------\n\n\n",
3973
+ "code": "# kol-popover-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nA button that toggles the visibility of a popover overlay containing arbitrary content.\nThe popover uses the native HTML Popover API for lightweight, non-modal overlays.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_inline` | `_inline` | Defines whether the component is displayed as a standalone block or inline without enforcing a minimum size of 44px. | `boolean \\| undefined` | `false` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_popoverAlign` | `_popover-align` | Defines where to show the Popover preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tabIndex` | `_tab-index` | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `hidePopover() => Promise<void>`\n\nHides the popover programmatically.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `showPopover() => Promise<void>`\n\nShows the popover programmatically.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | --------------------------------------------------------------- |\n| | The popover content (displayed when the button is clicked). |\n| `\"expert\"` | Custom label content for the button (when `_label` is `false`). |\n\n\n----------------------------------------------\n\n\n",
3942
3974
  "kind": "spec"
3943
3975
  },
3944
3976
  {
@@ -3947,7 +3979,7 @@
3947
3979
  "name": "progress",
3948
3980
  "description": "The Progress component visualizes the completion status of a task or process. It supports both determinate (percentage-based) and indeterminate variants.",
3949
3981
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/progress.md",
3950
- "code": "# kol-progress\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Progress** component visualizes the completion status of a task or process. It supports both determinate (percentage-based) and indeterminate variants.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------- | ----------- |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n| `_max` _(required)_ | `_max` | Defines the maximum value of the element. | `number` | `undefined` |\n| `_unit` | `_unit` | Defines the unit of the step values (not shown). | `string \\| undefined` | `undefined` |\n| `_value` _(required)_ | `_value` | Defines the value of the element. | `number` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"bar\" \\| \"cycle\" \\| undefined` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3982
+ "code": "# kol-progress\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Progress** component visualizes the completion status of a task or process. It supports both determinate (percentage-based) and indeterminate variants.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n| `_max` _(required)_ | `_max` | Defines the maximum value of the element. | `number` | `undefined` |\n| `_unit` | `_unit` | Defines the unit of the step values (not shown). | `string \\| undefined` | `undefined` |\n| `_value` _(required)_ | `_value` | Defines the value of the element. | `number` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"bar\" \\| \"cycle\" \\| undefined` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
3951
3983
  "kind": "spec"
3952
3984
  },
3953
3985
  {
@@ -3956,7 +3988,7 @@
3956
3988
  "name": "quote",
3957
3989
  "description": "The Quote component has two variants: a short inline (inline) and an indented block (block) variant. Both variants include a link to the source of the quote.",
3958
3990
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/quote.md",
3959
- "code": "# kol-quote\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Quote** component has two variants: a short inline (`inline`) and an indented block (`block`) variant. Both variants include a link to the source of the quote.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ----------- |\n| `_href` _(required)_ | `_href` | Sets the target URI of the link or citation source. | `string` | `undefined` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n| `_quote` _(required)_ | `_quote` | Defines the text of the quote. | `string` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"block\" \\| \"inline\" \\| undefined` | `'inline'` |\n\n\n----------------------------------------------\n\n\n",
3991
+ "code": "# kol-quote\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Quote** component has two variants: a short inline (`inline`) and an indented block (`block`) variant. Both variants include a link to the source of the quote.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | ----------- |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `undefined` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string \\| undefined` | `undefined` |\n| `_quote` _(required)_ | `_quote` | Defines the text of the quote. | `string` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `\"block\" \\| \"inline\" \\| undefined` | `'inline'` |\n\n\n----------------------------------------------\n\n\n",
3960
3992
  "kind": "spec"
3961
3993
  },
3962
3994
  {
@@ -3965,7 +3997,7 @@
3965
3997
  "name": "select",
3966
3998
  "description": "Sets focus on the internal element.",
3967
3999
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/select.md",
3968
- "code": "# kol-select\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this select. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` _(required)_ | `_options` | Options the user can choose from. | `(Option<StencilUnknown> \\| Optgroup<StencilUnknown>)[] \\| string` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tabIndex` | `_tab-index` | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `StencilUnknown[] \\| boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown[] | StencilUnknown | undefined>`\n\nReturns the selected values.\n\n#### Returns\n\nType: `Promise<StencilUnknown | StencilUnknown[]>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
4000
+ "code": "# kol-select\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this select. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_multiple` | `_multiple` | Makes the input accept multiple inputs. | `boolean \\| undefined` | `false` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` _(required)_ | `_options` | Options the user can choose from. | `(Option<StencilUnknown> \\| Optgroup<StencilUnknown>)[] \\| string` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tabIndex` | `_tab-index` | Defines which tab-index the primary element of the component has. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex) | `number \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `StencilUnknown[] \\| boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown[] | StencilUnknown | undefined>`\n\nReturns the selected values.\n\n#### Returns\n\nType: `Promise<StencilUnknown | StencilUnknown[]>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
3969
4001
  "kind": "spec"
3970
4002
  },
3971
4003
  {
@@ -3974,7 +4006,7 @@
3974
4006
  "name": "single-select",
3975
4007
  "description": "The SingleSelect component creates a dropdown list from which exactly one predefined option can be selected.",
3976
4008
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/single-select.md",
3977
- "code": "# kol-single-select\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **SingleSelect** component creates a dropdown list from which exactly one predefined option can be selected.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Uses ElementInternals.ariaDetailsElements 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). | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasClearButton` | `_has-clear-button` | Shows the clear button if enabled. | `boolean \\| undefined` | `true` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames (e.g. `icons=\"fa-solid fa-user\"`). | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` _(required)_ | `_options` | Options the user can choose from. | `Option<StencilUnknown>[] \\| string` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `null` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
4009
+ "code": "# kol-single-select\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **SingleSelect** component creates a dropdown list from which exactly one predefined option can be selected.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this input. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasClearButton` | `_has-clear-button` | Shows the clear button if enabled. | `boolean \\| undefined` | `true` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames (e.g. `icons=\"fa-solid fa-user\"`). | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_options` _(required)_ | `_options` | Options the user can choose from. | `Option<StencilUnknown>[] \\| string` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `null` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ----------------------------- |\n| | The label of the input field. |\n\n\n----------------------------------------------\n\n\n",
3978
4010
  "kind": "spec"
3979
4011
  },
3980
4012
  {
@@ -4009,7 +4041,7 @@
4009
4041
  "name": "split-button",
4010
4042
  "description": "The SplitButton component can be used to display a two-part button. The primary button is typically used for a main action, while the secondary button opens a context menu (Popover) that contains additional actions.",
4011
4043
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/split-button.md",
4012
- "code": "# kol-split-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **SplitButton** component can be used to display a two-part button. The primary button is typically used for\na main action, while the secondary button opens a context menu (`Popover`) that contains additional actions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `'normal'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closePopup() => Promise<void>`\n\nCloses the dropdown.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the dropdown. |\n\n\n----------------------------------------------\n\n\n",
4044
+ "code": "# kol-split-button\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **SplitButton** component can be used to display a two-part button. The primary button is typically used for\na main action, while the secondary button opens a context menu (`Popover`) that contains additional actions.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------- |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_ariaControls` | `_aria-controls` | Defines which elements are controlled by this component. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls) | `string \\| undefined` | `undefined` |\n| `_ariaDescription` | `_aria-description` | Defines the value for the aria-description attribute. | `string \\| undefined` | `undefined` |\n| `_ariaExpanded` | `_aria-expanded` | Defines whether the interactive element of the component expanded something. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded) | `boolean \\| undefined` | `undefined` |\n| `_ariaSelected` | `_aria-selected` | Defines whether the interactive element of the component is selected (e.g. role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected) | `boolean \\| undefined` | `undefined` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_icons` | `_icons` | Defines the icon classnames. | `KoliBriHorizontalIcons & KoliBriVerticalIcons \\| string \\| 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| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for button events. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_role` | `_role` | <span class=\"text-red-500\">**[DEPRECATED]**</span> We prefer the semantic role of the HTML element and do not allow for customization. We will remove this prop in the future.<br/><br/>Defines the role of the components primary element. | `\"tab\" \\| \"treeitem\" \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_type` | `_type` | Defines either the type of the component or of the components interactive element. | `\"button\" \\| \"reset\" \\| \"submit\" \\| undefined` | `'button'` |\n| `_value` | `_value` | Defines the value of the element. | `boolean \\| null \\| number \\| object \\| string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `'normal'` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `closePopup() => Promise<void>`\n\nCloses the dropdown.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<StencilUnknown>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<StencilUnknown>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | ------------------------------------------------------- |\n| | Allows arbitrary HTML to be inserted into the dropdown. |\n\n\n----------------------------------------------\n\n\n",
4013
4045
  "kind": "spec"
4014
4046
  },
4015
4047
  {
@@ -4018,7 +4050,7 @@
4018
4050
  "name": "table-stateful",
4019
4051
  "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.",
4020
4052
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateful.md",
4021
- "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.). | `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; onSortChange?: EventValueOrEventCallback<Event, SortChangeEventPayload> \\| undefined; }` | `undefined` |\n| `_pagination` | `_pagination` | Defines whether to show the data distributed over multiple pages. | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _label?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition` | `_pagination-position` | Controls the position of the pagination. | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n### `resetSort() => Promise<void>`\n\nResets the sort state to the default values defined in the `_headers` prop.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
4053
+ "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; onSortChange?: EventValueOrEventCallback<Event, SortChangeEventPayload> \\| undefined; }` | `undefined` |\n| `_pagination` | `_pagination` | Defines whether to show the data distributed over multiple pages. | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _label?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition` | `_pagination-position` | Controls the position of the pagination. | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n### `resetSort() => Promise<void>`\n\nResets the sort state to the default values defined in the `_headers` prop.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
4022
4054
  "kind": "spec"
4023
4055
  },
4024
4056
  {
@@ -4026,7 +4058,7 @@
4026
4058
  "group": "spec",
4027
4059
  "name": "table-stateless",
4028
4060
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateless.md",
4029
- "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.). | `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 \\| { onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSortChange?: EventValueOrEventCallback<Event, SortChangeEventPayload> \\| 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",
4061
+ "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 \\| { onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSortChange?: EventValueOrEventCallback<Event, SortChangeEventPayload> \\| 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",
4030
4062
  "kind": "spec"
4031
4063
  },
4032
4064
  {
@@ -4044,7 +4076,7 @@
4044
4076
  "name": "textarea",
4045
4077
  "description": "The Textarea component provides a larger input field for content. Unlike InputText, it also allows extensive content to be entered, including line breaks.",
4046
4078
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/textarea.md",
4047
- "code": "# kol-textarea\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Textarea** component provides a larger input field for content. Unlike InputText, it also allows extensive content to be entered, including line breaks.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_adjustHeight` | `_adjust-height` | Adjusts the height of the element to its content. | `boolean \\| undefined` | `false` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this textarea. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `false` to enable the expert slot. | `string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Gibt die EventCallback-Funktionen für das Input-Event an. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_resize` | `_resize` | Defines whether and in which direction the size of the input can be changed by the user. (https://developer.mozilla.org/de/docs/Web/CSS/resize) In version 3 (v3), horizontal resizing is abolished. The corresponding property is then reduced to the properties `vertical` (default) and `none`. | `\"none\" \\| \"vertical\" \\| undefined` | `'vertical'` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_spellCheck` | `_spell-check` | Defines whether the browser should check the spelling and grammar. | `boolean \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
4079
+ "code": "# kol-textarea\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Textarea** component provides a larger input field for content. Unlike InputText, it also allows extensive content to be entered, including line breaks.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ |\n| `_accessKey` | `_access-key` | Defines the key combination that can be used to trigger or focus the component's interactive element. | `string \\| undefined` | `undefined` |\n| `_adjustHeight` | `_adjust-height` | Adjusts the height of the element to its content. | `boolean \\| undefined` | `false` |\n| `_ariaDetails` | `_aria-details` | References an external element by ID that provides accessible details for this textarea. Behavior and screen reader support: see `AriaDetailsPropType` and KNOWN_ISSUES.md. | `string \\| undefined` | `undefined` |\n| `_disabled` | `_disabled` | Makes the element not focusable and ignore all events. | `boolean \\| undefined` | `false` |\n| `_hasCounter` | `_has-counter` | Shows a character counter for the input element. | `boolean \\| undefined` | `false` |\n| `_hideLabel` | `_hide-label` | Hides the caption by default and displays the caption text with a tooltip when the interactive element is focused or the mouse is over it. | `boolean \\| undefined` | `false` |\n| `_hideMsg` | `_hide-msg` | Hides the error message but leaves it in the DOM for the input's aria-describedby. | `boolean \\| undefined` | `false` |\n| `_hint` | `_hint` | Defines the hint text. | `string \\| undefined` | `''` |\n| `_icons` | `_icons` | Defines the icon classnames. | `string \\| undefined \\| { right?: IconOrIconClass \\| undefined; left?: IconOrIconClass \\| undefined; }` | `undefined` |\n| `_infoPopover` | -- | Defines the informational popover after the label. | `Omit<PopoverButtonProps, \"_icons\" \\| \"_hideLabel\" \\| \"_inline\"> & { _content: string; _icons: IconsPropType; } \\| undefined` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). Set to `''` to enable the expert slot. | `LabelSegment[] \\| string` | `undefined` |\n| `_maxLength` | `_max-length` | Defines the maximum number of input characters. | `number \\| undefined` | `undefined` |\n| `_maxLengthBehavior` | `_max-length-behavior` | Defines the behavior when maxLength is set. 'hard' sets the maxlength attribute, 'soft' shows a character counter without preventing input. | `\"hard\" \\| \"soft\" \\| undefined` | `'hard'` |\n| `_msg` | `_msg` | Defines the properties for a message rendered as Alert component. | `Omit<AlertProps, \"_label\" \\| \"_level\" \\| \"_on\" \\| \"_variant\" \\| \"_hasCloser\"> & { _description: string; } \\| string \\| undefined` | `undefined` |\n| `_name` | `_name` | Defines the technical name of an input field. | `string \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for input events. | `InputTypeOnBlur & InputTypeOnClick & InputTypeOnChange & InputTypeOnFocus & InputTypeOnInput & InputTypeOnKeyDown \\| undefined` | `undefined` |\n| `_placeholder` | `_placeholder` | Defines the placeholder for input field. To be shown when there's no value. | `string \\| undefined` | `undefined` |\n| `_readOnly` | `_read-only` | Makes the input element read only. | `boolean \\| undefined` | `false` |\n| `_required` | `_required` | Makes the input element required. | `boolean \\| undefined` | `false` |\n| `_resize` | `_resize` | Defines whether and in which direction the size of the input can be changed by the user. (https://developer.mozilla.org/de/docs/Web/CSS/resize) In version 3 (v3), horizontal resizing is abolished. The corresponding property is then reduced to the properties `vertical` (default) and `none`. | `\"none\" \\| \"vertical\" \\| undefined` | `'vertical'` |\n| `_rows` | `_rows` | Maximum number of visible rows of the element. | `number \\| undefined` | `undefined` |\n| `_shortKey` | `_short-key` | Adds a visual shortcut hint after the label and instructs the screen reader to read the shortcut aloud. | `string \\| undefined` | `undefined` |\n| `_spellCheck` | `_spell-check` | Defines whether the browser should check the spelling and grammar. | `boolean \\| undefined` | `undefined` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n| `_touched` | `_touched` | Shows if the input was touched by a user. | `boolean \\| undefined` | `false` |\n| `_value` | `_value` | Defines the value of the element. | `string \\| undefined` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `click() => Promise<void>`\n\nClicks the primary interactive element inside this component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nSets focus on the internal element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `getValue() => Promise<string | undefined>`\n\nReturns the current value.\n\n#### Returns\n\nType: `Promise<string | undefined>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---------- | -------------------------------------------------------------------------------------------------------- |\n| `\"expert\"` | Custom label content, e.g. for rich text or icons. https://public-ui.github.io/docs/concepts/expert-slot |\n\n\n----------------------------------------------\n\n\n",
4048
4080
  "kind": "spec"
4049
4081
  },
4050
4082
  {
@@ -4071,7 +4103,7 @@
4071
4103
  "name": "tree-item",
4072
4104
  "description": "Collapses the tree item.",
4073
4105
  "path": "packages/tools/mcp/node_modules/@public-ui/components/doc/tree-item.md",
4074
- "code": "# kol-tree-item\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------- | ----------- |\n| `_active` | `_active` | If set (to true) the tree item is the active one. | `boolean \\| undefined` | `undefined` |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string` | `undefined` |\n| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `collapse() => Promise<void>`\n\nCollapses the tree item.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `expand() => Promise<void>`\n\nExpands the tree item.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nFocuses the link element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `isOpen() => Promise<boolean>`\n\nReturns whether the tree item is expanded.\n\n#### Returns\n\nType: `Promise<boolean>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | --------------------------------------- |\n| | Further Children as TreeItem Components |\n\n\n----------------------------------------------\n\n\n",
4106
+ "code": "# kol-tree-item\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------- | ----------- |\n| `_active` | `_active` | If set (to true) the tree item is the active one. | `boolean \\| undefined` | `undefined` |\n| `_href` _(required)_ | `_href` | Defines the target URI of the link. | `string` | `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| `_open` | `_open` | Opens/expands the element when truthy, closes/collapses when falsy. | `boolean \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `collapse() => Promise<void>`\n\nCollapses the tree item.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `expand() => Promise<void>`\n\nExpands the tree item.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nFocuses the link element.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `isOpen() => Promise<boolean>`\n\nReturns whether the tree item is expanded.\n\n#### Returns\n\nType: `Promise<boolean>`\n\n\n\n\n## Slots\n\n| Slot | Description |\n| ---- | --------------------------------------- |\n| | Further Children as TreeItem Components |\n\n\n----------------------------------------------\n\n\n",
4075
4107
  "kind": "spec"
4076
4108
  },
4077
4109
  {