@public-ui/mcp 4.6.0-rc.1 → 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.
- package/package.json +2 -2
- package/shared/sample-index.json +78 -28
- package/shared/template-index.json +108 -108
package/shared/sample-index.json
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
|
-
"generatedAt": "2026-11-
|
|
3
|
+
"generatedAt": "2026-11-12T15:26:48.919Z",
|
|
4
4
|
"buildMode": "ci",
|
|
5
5
|
"counts": {
|
|
6
|
-
"total":
|
|
7
|
-
"totalDocs":
|
|
8
|
-
"totalSpecs":
|
|
6
|
+
"total": 350,
|
|
7
|
+
"totalDocs": 69,
|
|
8
|
+
"totalSpecs": 53,
|
|
9
9
|
"totalSamples": 208,
|
|
10
|
-
"totalScenarios":
|
|
10
|
+
"totalScenarios": 20
|
|
11
11
|
},
|
|
12
12
|
"repo": {
|
|
13
|
-
"commit": "
|
|
14
|
-
"branch": "
|
|
13
|
+
"commit": "b219b377e2228de2510d554556620e074d3360ee",
|
|
14
|
+
"branch": "develop",
|
|
15
15
|
"repoUrl": "https://github.com/public-ui/kolibri"
|
|
16
16
|
}
|
|
17
17
|
},
|
|
@@ -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/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- `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- **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",
|
|
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
|
{
|
|
@@ -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
|
{
|
|
@@ -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
|
{
|
|
@@ -414,7 +414,16 @@
|
|
|
414
414
|
"name": "FORM_FIELD_SKELETON_MIGRATION_PLAN",
|
|
415
415
|
"description": "Übergreifender Plan für die Skeleton-Migration der 14 Formularfelder von kol-combobox bis kol-textarea (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.",
|
|
416
416
|
"path": "docs/FORM_FIELD_SKELETON_MIGRATION_PLAN.md",
|
|
417
|
-
"code": "# Migrationsplan: Formularfelder auf Skeleton\n\nÜbergreifender Plan für die Skeleton-Migration der 14 Formularfelder von `kol-combobox` bis `kol-textarea` (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.\n\nStand: 27.09.2026, `@public-ui/components` 4.5.0-rc.0.\n\n## Ausgangslage\n\nVor der Migration lief keines der 14 Felder auf Skeleton. Der Legacy-Stack besteht aus:\n\n- Controller-Kette `AssociatedInputController → ControlledInputController → InputController → InputIconController → Feld-Controller`\n- State-Wrapper in `functional-component-wrappers/`, die die alten FCs in `functional-components/` rendern\n- Validatoren aus `schema/props/`\n\nAus dem Formularumfeld ist bisher nur `kol-form` auf Skeleton umgestellt.\n\n| Feld | LOC `shadow.tsx` | Render-Stack heute | Besonderheit |\n| -------------------- | --------------------------- | ------------------------------------------- | --------------------------------------------------------------- |\n| `kol-input-color` | 380 | FormField + InputContainer + Input („Trio\") | dünnstes Feld, kein `_required` |\n| `kol-input-email` | 489 | Trio | Controller erbt von Text → Password, Counter |\n| `kol-input-password` | 511 | Trio + IconButton (`KolButtonWcTag`) | `_visibilityToggle`, Basisklasse für Text und Email |\n| `kol-input-text` | 620 | Trio + Clear-Button | `_type`, Selection-API-Methoden |\n| `kol-textarea` | 498 | FormField + InputContainer + TextArea | `_adjustHeight`, `_resize`, `_rows`, Counter |\n| `kol-input-number` | 551 | Trio + Step-Buttons | Feature-Flag `inputNumberButtons`, genutzt von `table-settings` |\n| `kol-input-range` | 499 | 2× Input (range + number) + Suggestions | min/max/step, zwei synchrone Inputs |\n| `kol-input-date` | 513 (+ 219 Controller) | Trio | Date↔ISO, 5 `_type`s, `reset()` |\n| `kol-input-file` | 450 | Trio + Browse-Button (`KolButtonWcTag`) | kein `_value`, FileList, `_accept`, Drag & Drop, `reset()` |\n| `kol-input-checkbox` | 457 | FormField + FieldControl + Checkbox | Varianten default/switch/button, genutzt von `table-settings` |\n| `kol-input-radio` | 458 | FormField (fieldset) + FieldControl + Radio | `_options`, `_orientation`, alte Utils `element-click`/`-focus` |\n| `kol-select` | 222 + 404 (`kol-select-wc`) | FormField + InputContainer + NativeSelect | `pagination` rendert `kol-select-wc` direkt |\n| `kol-combobox` | 756 | Trio + CustomSuggestions + `@Listen` | Listbox, nahezu Zwilling von single-select |\n| `kol-single-select` | 849 | Trio + CustomSuggestions + `@Listen` | größtes Feld, offene Bugs #10501/#10617 |\n\n## Rahmenbedingungen\n\n- **Zero visual delta, BEM bleibt.** DOM und Klassen (`.kol-form-field`, `.kol-input-container`, `.kol-field-control` …) bleiben byte-identisch. Themes werden nicht angefasst, es gibt keinen CLI-/SCSS-Migrations-Task. Das Pixel-Gate verlangt 0 Diffs pro Theme.\n- **Formular-Anbindung 1:1 als Behavior.** Die heutige Semantik (versteckte native Elemente im Light DOM, `_syncValueBySelector`, `ariaDetails` über `attachInternals`) wandert aus der Controller-Kette in ein wiederverwendbares `FormAssociationBehavior`, das auch `kol-button` nutzt. Einen Umstieg auf natives `formAssociated` gibt es in dieser Migration nicht.\n- **Identische öffentliche API.** Gleiche `@Prop`/`@Method`-Member, Alias-Typen, Defaults und JSDoc. Die Oberfläche ist vor der Migration in `_skeleton/public-api/<komponente>.spec.ts` festgenagelt.\n\n## Leitplanken\n\n- **Strangler statt Big Bang.** Der neue Stack entsteht unter `internal/functional-components/form-field/` neben dem alten. Ein Legacy-Modul wird in dem PR gelöscht, der seinen letzten Import entfernt.\n- **Keine Bugfixes in Migrations-PRs.** Bekannte Fehler (z. B. #10501, #10617) bekommen eigene PRs, vor oder nach der Migration.\n- **Innere Tags bleiben.** `KolButtonWcTag` (IconButton, Clear-, Browse- und Visibility-Button) und `KolPopoverButtonWcTag` (Label-`_infoPopover`) bleiben wegen Zero-Delta stehen. Das ist eine begründete Ausnahme nach Fallstrick 8 im Skill `migrate-to-skeleton`.\n- **Grenze von DD16.** Stencil liest Decorators nur aus der konkreten Klasse. Alle `@Prop`/`@Watch`/`@Method` samt JSDoc bleiben in jeder Komponente, Basisklassen bündeln nur Logik. Höchstens zwei Ebenen unter `BaseWebComponent`.\n- **Basisklasse nach G1 eingefroren.** Änderungen an `BaseFormFieldWebComponent` kommen nur als eigenes PR, mit Pixel-Gate über alle bereits migrierten Felder.\n- **Konfliktstellen.** `internal/props/index.ts`, `schema/bem-registry.ts` und die Pin-Dateien: nur anhängen, Reihenfolge zwischen den Spuren absprechen.\n\n### Abnahme-Gates je Komponenten-PR\n\n1. Der Public-API-Pin ist unverändert und zeigt jetzt auf `component.tsx`. Die Klasse implementiert `*Props`.\n2. Die Jest-`.snap`-Dateien sind unverändert.\n3. `node scripts/snapshots-docker.mjs <theme> --check` meldet 0 Diffs für default, bwst, desy, kern und ecl (ec/eu).\n4. Die Verhaltensverträge aus G0 sind grün.\n5. Die geteilten E2E-Helfer `src/e2e/{input-msg,input-value-reflection,input-character-limit}.ts` sind grün.\n6. Keine Imports mehr aus `@deprecated/input`, `input-adapter-leanup`, `functional-component-wrappers` oder den alten `functional-components/*`.\n7. `form.e2e` ist grün: Ein Klick in der Fehlerliste fokussiert das Feld über seinen `focus()`.\n\n## Reihenfolge und Abhängigkeiten\n\n```\nG0 ─► G1.1 ─┬─► G1.2 ──┐\n └─► G1.3 ──┴─► G1.4 (Pilot input-color)\n ├─► G2 Textfelder (Spur A)\n ├─► G3 a | b | c (Spur B)\n └─► G4-Vorbereitung ─► G4 ─► G5 (Spur C)\nRückbau-Inkremente am Ende jeder Gruppe; finaler Rückbau (G6) nach G2–G5\n```\n\n## Gruppen\n\n### G0 – Absicherung\n\nKein Produktivcode, Voraussetzung für alles. Die Gates greifen nur, wenn vorher festgehalten ist, was „unverändert\" heißt: API, Verhalten und Pixel.\n\n- ✅ Public-API-Pins für alle 14 Tags und `kol-select-wc` (als interner Vertrag), zunächst gegen `shadow.tsx`. Jede Komponente hat eine eigene Datei unter `_skeleton/public-api/`, damit parallele Spuren keine Merge-Konflikte bekommen.\n- ✅ Verhaltensverträge pro Feld: Reihenfolge und Payload von `kolChange`/`kolInput`/`kolFocus`/`kolBlur`/`kolKeydown`/`kolClick` und der `_on`-Callbacks; `FormData` eines nativen `<form>` für Checkbox, `select` multiple, File und Radio mit Objektwerten; `_syncValueBySelector`; `_touched` nach Blur. Die Verträge sind Playwright-Tests (`*.e2e.ts`), weil versteckte Light-DOM-Elemente, `attachInternals`, `FormData` sowie Fokus und Tastatur nur im echten Browser verlässlich prüfbar sind. Sie nutzen die Helfer aus `src/e2e/`. Reine Umrechnungen ohne Browserverhalten (z. B. Date↔ISO in G3) werden als Jest-Tests der Hilfsfunktionen geprüft.\n - Der gemeinsame Helfer `testInputBehaviorContract` in `src/e2e/input-behavior-contract.ts` zeichnet Events und Callbacks auf; jedes Feld pinnt darin sein heutiges Verhalten. Alle 14 Felder sind gepinnt, dazu die Varianten Radio mit Objektwerten und `kol-select` mit `_multiple` (Option `variant`).\n - Befunde aus den Verträgen: Die gepinnten Abläufe beschreiben den heutigen Stand, auch wo er inkonsistent ist. Korrekturen kommen als eigene PRs nach der jeweiligen Migration.\n - Standard (G1.4, alle Felder außer den unten genannten Abweichungen): Je Aktion kommt zuerst das KoliBri-Event am Host, dann der `_on`-Callback, dann das native Event. Natives `input`/`change` endet an der Shadow-Grenze.\n - Startwert ohne Vorgabe: `kol-input-color` `#000000` (aus dem inneren Input in `componentDidLoad`), `kol-input-range` `50`, `kol-input-checkbox` `true`, `kol-input-radio` und `kol-single-select` `null`, alle anderen `undefined`.\n - G3: Payloads sind typisiert – number und range liefern Zahlen, date den ISO-String, file eine `FileList`. Für file bleibt ein Text-Input als `_syncValueBySelector`-Ziel leer.\n - G4: checkbox und radio senden kein KoliBri-`click` und keinen `onClick` (`onClick: undefined` in `shadow.tsx`). Stattdessen erreicht das native `click` den Host vor `input`/`change`.\n - G5: `kol-single-select` sendet beim Blur zuerst das native Event, dann das KoliBri-Event und den Callback. `kol-select` setzt `_touched` am eigenen Host nicht, das innere `kol-select-wc` hält den Zustand. Außerdem überträgt `kol-select` einen Einzelwert weder in `FormData` noch in das `_syncValueBySelector`-Ziel, weil das versteckte `<select multiple>` nur Array-Werte übernimmt. Mit `_multiple` stehen alle gewählten Werte in `FormData`. Issues: #11014 (`_touched`, behoben in G5.2), #11015 (Einzelwert, behoben nach G5.4).\n - Radio mit Objektwerten liefert das Objekt als Payload und überträgt es als JSON-String in `FormData` und an `_syncValueBySelector`.\n - Formular-Anbindung heute: Das versteckte Element im Light DOM entsteht nur mit `register(…, { reflectInputValues: true })`, seinen `name` setzt der Controller nur im Experimental-Mode. Nur mit beidem steht das Feld in `FormData`. Der Vertrag pinnt alle drei Fälle, der Test ruft `register` dafür aus dem Build unter Test auf.\n- ✅ Visual-Samples ergänzen für msg, hint, disabled, hideLabel, infoPopover, Counter, Icons, `inputNumberButtons` an/aus und die Checkbox-Varianten. Neue Samples erzeugen neue Baselines und gehören in ein eigenes PR vor der ersten Migration.\n - Vorhanden: msg, hint, disabled, hideLabel, infoPopover und Icons für alle 14 Felder über `partials/cases.tsx`/`variants.tsx`, Counter bei `input-text` und `textarea`, Checkbox-Varianten `basic`/`button`/`switch`.\n - `inputNumberButtons` setzt das Theme (`theme-default` `'show'`, `theme-kern` `'hide'`); die bestehenden `input-number`-Baselines decken damit beide Zustände ab.\n - Ergänzt in #11017: Counter-Routen für `kol-input-email` und `kol-input-password`, Hint-Block für `kol-input-number`.\n- ✅ Toten Code löschen: `functional-components/inputs/Combobox/Combobox.tsx`.\n\n### G1 – Fundament + Pilot `kol-input-color` (#9673, #9577)\n\nAlle 14 Felder teilen Basis-Props, die Label/Hint/Msg-Hülle, die Formular-Anbindung und die Event-Logik. Das wird einmal gebaut und am dünnsten Feld geprüft, damit die Basisklasse an einem echten Fall entsteht. G1 besteht aus sechs PRs: G1.0 #11037, G1.1 #11038, G1.2 #11044, G1.3a #11045, G1.3b #11046 und G1.4 #11049. Alle sind gemergt.\n\n```\nG1.0 Testlücken ───────────────┬──────────────────────────────────────────────┐\nG1.1 Props ─┬─► G1.2 FormAssociationBehavior (+ kol-button) ─► SSR-Fix (eigener PR)\n │ (braucht G1.0 und G1.1) │\n └─► G1.3a FormField ─► G1.3b Container/Input ──────────────────────┴─► G1.4 Basis + kol-input-color\n```\n\n0. **Testlücken** (nur Tests):\n - Formular-Anbindung von `kol-button` gepinnt. Es entsteht kein verstecktes Formularelement, weil der Adapter in `button/base.tsx` `_name` bei der Konstruktion nicht kennt (#11036); `_syncValueBySelector` wirkt im Experimental-Mode.\n - Gate 7 mit einem `kol-input-color` als Ziel der Fehlerliste.\n - Tooltip bei `_hideLabel` für `kol-input-color`. Befund: Hat das Feld den Fokus, schließt Escape den Tooltip nicht. Das Feld sendet sein eigenes `keydown`-CustomEvent am Host, das vor der nativen Taste am Dokument ankommt und den einmaligen Escape-Listener des Tooltips verbraucht (#11032, verwandt #11033).\n - Jest-Snapshots aller Felder zusätzlich mit `_hideLabel`, `_infoPopover`, sichtbarer Msg und `_variant`.\n1. **Basis-Props** in `internal/props/`: ariaDetails, autoComplete, hideMsg, hint, `horizontalIconsProp` (Icons-Objekt der Inputs, `icons.ts` bleibt unverändert), infoPopover, `inputCallbacksProp` (`_on`), msg, readOnly, required, suggestions, syncValueBySelector (nur für das Behavior), touched und der String-Wert. `tooltipAlignProp` wird wiederverwendet, der Feld-Default `'top'` im `apply` neu gesetzt. Der veröffentlichte Typ `FormFieldLabelInfoPopoverProps` zieht in einem Schritt für alle Felder nach `schema/props/`; ein teilweiser Umzug würde in `components.d.ts` einen Alias `…1` erzeugen.\n2. **`FormAssociationBehavior`**: übernimmt `input-adapter-leanup/associated.controller.ts` 1:1, einschließlich der späten Host-Zuweisung im Konstruktor. `AssociatedInputController` wird zur Fassade über das Behavior, damit die G0-Verträge es sofort für alle Felder prüfen. `button/base.tsx` wird im selben PR umgestellt; der Button-Pin bleibt unverändert.\n3. **Shell-FCs** unter `internal/functional-components/form-field/`, nur für die Hülle von `kol-input-color`: G1.3a FormField (Label, Hint, Msg, Counter, Tooltip, Zeichengrenzen-Hinweis) mit dem ARIA-Helfer aus `getRenderStates`, G1.3b InputContainer mit Adornments, IconButton, Input und Suggestions. Neue Blöcke in `schema/bem-registry.ts`. Die alten FCs werden Adapter auf die neuen, damit Hydrate-Snapshot und Pixel-Gate die Hülle sofort über alle Felder prüfen. TextArea kommt in G2, FieldControl/Checkbox/Radio in G4, NativeSelect/Option(List)/CustomSuggestions in G5. Die `fieldset`-Wurzel von radio bleibt bis G4 auf dem alten Pfad, weil `BemRootNodeFC` nur `div` rendert.\n4. **`BaseFormFieldWebComponent`** (DD16): `apply*` der Basis-Props, ein eigenes `TooltipBehavior` pro Instanz statt der modulglobalen Map in `FormField.tsx`, Formular-Anbindung, Event-Behandlung als Ersatz für `InputController` (Reihenfolge: KoliBri-Event, dann Callback) und Render-Helfer. Damit wird `kol-input-color` migriert.\n - Die Basis ist generisch über die Feld-API. Sie greift über einen dokumentierten Self-Cast (`shared`) auf die Basis-Props zu und liefert die FormField-Props mit `getFormFieldProps()`. Gerendert wird in der konkreten Klasse, wie bei `BaseButtonWebComponent`.\n - Die Props an `InputFC` bildet die konkrete Klasse in der Schlüsselreihenfolge der alten State-Wrapper. Props, die der Legacy-State nur bei gesetztem Wert enthielt, zum Beispiel `accessKey` und `aria-keyshortcuts`, übergibt sie nur, wenn ein Wert gesetzt ist. Nur so bleiben die Attributreihenfolge im Hydrate-Snapshot und das DOM unverändert.\n - `_label={false}` bleibt wie bisher der Expert-Slot (`''`). `labelWithExpertSlotProp` allein würde daraus den String `'false'` machen.\n\nEntscheidungen:\n\n- Die Basis-Config enthält nur Props, die alle 14 Felder identisch haben: ariaDetails, disabled, hideLabel, hideMsg, hint, infoPopover, label, msg, name, on, tooltipAlign, touched. `WebComponentInterface` verlangt für jede Config-Prop einen Watcher.\n- Die Basisklasse ist generisch über die Feld-API. TypeScript löst `ResolvedProps<Api>` für ein generisches `Api` nicht auf, deshalb greift sie über einen einzigen, dokumentierten Self-Cast auf die Basis-Props zu.\n- Bewusste Abweichungen der Prop-Factory, wie in allen bisherigen Skeleton-Migrationen: `undefined` führt zum Default statt den alten Wert zu behalten, `normalizeBoolean` akzeptiert `'true'`/`'false'`, ungültige Werte werden verworfen.\n- `data-testid=\"input-counter\"`/`\"input-counter-aria\"` bleiben bis G2, weil `e2e/input-character-limit.ts` sie braucht und der DOM byte-gleich bleiben muss.\n\nRisiken: Zusammenbau von `aria-describedby` (hint, msg, Counter, Hinweis zur Zeichengrenze; heutige Eigenheiten in #11035); Attribut- und Klassenreihenfolge im Hydrate-Snapshot; die beiden Fokus-Flags aus Controller und Komponente; `attachInternals(undefined)` bei SSR/Hydrate.\n\n### G2 – Textfelder: email → password → text, danach textarea (#9579, #9582, #9585, #9602)\n\nDie vier Felder hängen heute in der Kette `InputPasswordController → InputTextEmailController → InputText/InputEmail` und teilen placeholder, autoComplete, maxLength/hasCounter/maxLengthBehavior und den Counter. pattern haben nur die drei Inputs. `spellCheck` rendern input-text und textarea (#10863 wurde in #11073 behoben).\n\nG2 besteht aus sechs PRs:\n\n```\nG2.0 Testlücken (nur Tests) ────────────────────────────────────────────────────────┐\nG1.4 ─► G2.1 Props + CounterBehavior + TextAreaFC ─► G2.2 Basis + email ─► G2.3 password ─► G2.4 text ─► G2.5 textarea\n```\n\n- G2.0: Jest-Snapshots für Zähler, Zeichengrenze, Clear-Button, Visibility-Toggle, `_multiple`, `_pattern`, `_required` und `_resize`. Bisher pinnt kein Snapshot diese Fälle. Befunde, die die Migration 1:1 übernimmt: #11051 (`_adjustHeight` schrumpft nicht), #11052 (Zähler bei `_hasCounter`/`_maxLengthBehavior` zur Laufzeit), #11053 (`has-value` uneinheitlich), #11054 (devHint zu `_autoComplete`). Der Befund #10863 (`spellCheck`) wurde in #11073 behoben.\n- G2.1: Props der Textfelder in `internal/props/`; `CounterBehavior` unter `internal/functional-components/counter/` (besitzt `hasCounter`, `maxLength` und `maxLengthBehavior`, `CounterDomUpdater` ist bis G2.5 Fassade darüber); `TextAreaFC` mit dem neuen Block `kol-textarea` und das alte `inputs/TextArea` als Adapter; `getFormFieldProps()` der Basis reicht zusätzlich `required`, `readOnly`, `maxLength` und `counter` durch.\n- G2.2: `BaseTextInputWebComponent` (`internal/functional-components/text-input/`) für email, password und text, damit wird `kol-input-email` migriert.\n - Die Zähler-Props gehören dem `CounterBehavior` und stehen nicht in der Props-Config der Felder; die Watcher der Felder geben sie an das Behavior weiter.\n - Die Props an `InputFC` folgen der Schlüsselreihenfolge von `InputStateWrapper`. Props, die der Legacy-State nur gesetzt enthielt (`accessKey`, `maxlength`, `placeholder`, `pattern`, `aria-keyshortcuts`), werden nur übergeben, wenn ein Wert gesetzt ist; ein leerer Name wird nicht gerendert. Den Unterschied sieht nur der Hydrate-Snapshot, Jest verwirft leere Attribute.\n - `has-value` ist wie im Legacy-Code ein einfaches Feld ohne Re-Render (#11053).\n - Beim Laden werden Wert und Maximum ohne Zähler-Update übernommen, der Zähler wird in `componentDidLoad` gefüllt.\n - Icons und Smart-Button der Input-Container bildet `getInputAdornments()` (`form-field/adornments.tsx`) für alle migrierten Felder, auch für `kol-input-color`.\n- G2.3: `kol-input-password` auf `BaseTextInputWebComponent`, mit `visibilityToggle` und dem State `passwordVisible`. Der Kompatibilitätszweig `_variant === 'visibility-toggle'` (#10247) entfällt: Legacy verglich den bereits zu einem Array normalisierten `_variant` mit einem String, der Zweig griff also nie. Der G2.0-Snapshot pinnt das. `input-password/controller.ts` bleibt bis G2.4, weil `InputTextController` davon erbt.\n- G2.4: `kol-input-text` auf `BaseTextInputWebComponent`, mit `type` (auch als Root-Klasse), `spellCheck`, `suggestions`, Clear-Button bei `type=\"search\"` und den fünf Selection-Methoden. `has-value` folgt hier wie bisher jeder Wertänderung. Mit dem Feld fällt die Controller-Kette `InputPasswordController → InputTextEmailController → InputTextController` weg.\n- G2.5: `kol-textarea` erbt direkt von `BaseFormFieldWebComponent` und komponiert das `CounterBehavior`; die drei Zähler-Watcher wiederholen die Einzeiler der Textbasis, eine dritte Basisebene ist nicht erlaubt. Übernommen werden die Zeilenberechnung von `_adjustHeight` (wächst nur, #11051), das `setTimeout` in `componentDidLoad` für `_rows` und `style.resize`; `spellCheck` wird gerendert (#10863 wurde in #11073 behoben). Mit dem Feld fallen `CounterDomUpdater`, `TextAreaStateWrapper` und das alte `inputs/TextArea` samt Adapter-Test weg.\n- `CounterBehavior` ersetzt `utils/counter-dom-updater.ts`; das direkte DOM-Update ohne Re-Render bleibt erhalten.\n- textarea erbt direkt von `BaseFormFieldWebComponent` und nutzt das CounterBehavior.\n- Risiken: Selection-API und `_type` search/url/tel von input-text; Clear-Button und Visibility-Toggle; Datalist-IDs; `_adjustHeight`/`_resize` bei textarea.\n- Zusätzliche Abnahme: `input-character-limit` und `input-text.clear-button.e2e` grün; alle 16 React-Routen von input-text pixelgleich.\n\n### G3 – Wertetypen (#9581, #9584, #9578, #9580)\n\nDrei parallele Spuren: a) number → range, b) date, c) file. Die Felder nutzen die Standard-Hülle, müssen aber ihren Wert umwandeln.\n\n- Eigene Input-Props für min/max/step; die vorhandenen Meter-Props (Defaults 0/100) passen nicht.\n- a) Step-Buttons und Feature-Flag `inputNumberButtons`; range mit zwei synchronen Inputs und Suggestions. G3a besteht aus vier PRs:\n\n ```\n G2.5 ─► G3a.0 Testlücken ─► G3a.1 Props + Zahlen-Helfer ─► G3a.2 number ─► G3a.3 range\n ```\n\n - G3a.0: Jest-Snapshots für min/max/step, `_value` als Zahl, `NumberString`, `null` und `0`, die Namen und die Breitenformel von range. Befunde, die die Migration 1:1 übernimmt: #10861 (range klemmt nicht bei einer Grenze 0), #11075 (range synchronisiert beim Ziehen nicht), #11076 (range übernimmt ohne `_value` den Browser-Mittelwert), #11077 (negative und Exponent-Strings werden verworfen), #11053 (`has-value` fehlt bei number für `0`).\n - G3a.1: `inputMinProp`, `inputMaxProp`, `stepProp` und der Zahlenwert in `internal/props/` mit einer Normalisierung, die `validateNumber` 1:1 nachbildet; reine Hilfsfunktionen für den gemerkten Werttyp, das Parsen und die Klemmung von range; `getInputAdornments()` bekommt ein `startAdornment` vor dem linken Icon.\n - G3a.2: `kol-input-number` erbt direkt von `BaseFormFieldWebComponent`. Die Step-Buttons bleiben native `<button>` und folgen bei jedem Render dem Flag `inputNumberButtons`.\n - G3a.3: `kol-input-range` erbt direkt von `BaseFormFieldWebComponent`, mit zwei `InputFC` und dem Datalist neben dem Wrapper.\n - Eine gemeinsame Basis für number und range gibt es nicht: number schreibt `_value` bei jedem `input`, range erst bei `change` und klemmt dabei.\n\n- b) Date↔ISO-Logik aus `input-date/controller.ts` in Hilfsfunktionen, alle 5 `_type`s, Zeitzonen. G3b besteht aus drei PRs:\n\n ```\n G3a.3 ─► G3b.0 Testlücken ─► G3b.1 Props + Datums-Helfer ─► G3b.2 date\n ```\n\n - G3b.0: Jest-Snapshots für alle fünf `_type`s mit Wert, `_min`/`_max`, `_step` bei `time`, einen zum Typ unpassenden Wert, `null` sowie `_readOnly` und `_required`. Werte als `Date` pinnen weiter die e2e-Tests und `controller.spec.ts`, weil ein `Date` im Namen eines Snapshots von der Zeitzone abhängt.\n - G3b.1: der Typ und die Datums-Props (`_min`, `_max`, `_value`, abhängig von `_type` und `_step`) in `internal/props/`; die Umwandlung `Date` → ISO-String, die Kalenderwoche und die Formatprüfung je Typ als reine Hilfsfunktionen, die der Legacy-Controller sofort nutzt.\n - G3b.2: `kol-input-date` erbt direkt von `BaseFormFieldWebComponent`, mit `reset()`, dem Rückschreiben von `_value` beim Blur, wenn der Wert zwischen leer und gesetzt wechselt, Enter-Submit außer bei fokussiertem Kalender-Icon und dem unterdrückten Leerzeichen bei `_readOnly`.\n - Befund: `InputDateController.validateOn` legt einen Wrapper um `_on.onChange` in den State, den nichts liest; die Events rufen das `_on` der Prop. Die Migration übernimmt den Wrapper nicht, das Verhalten bleibt gleich.\n\n- c) FileList, Drag-&-Drop-Modifier, Browse-Button, übertragener Formularwert. G3c besteht aus drei PRs:\n\n ```\n G3b.2 ─► G3c.0 Testlücken ─► G3c.1 accept-Prop + Dateinamen-Helfer ─► G3c.2 file\n ```\n\n - G3c.0: Jest-Snapshots für `_accept`, `_multiple`, `_required`, ein Feld ohne Namen und `_accept` mit `_multiple`, Icons und Smart-Button. e2e für mehrere Dateien, `--has-file` bei Auswahl und `reset()`, den Formularwert nach Auswahl und Drop sowie den Ist-Stand beim Drop: Dateiname ohne `--has-file`, `change` vor `input` (#10865). Befund, den die Migration 1:1 übernimmt: `reset()` wirft bei Formular-Zuordnung einen TypeError (#11110).\n - G3c.1: `acceptProp` in `internal/props/` und ein reiner Helfer für den angezeigten Dateinamen, den die Legacy-Komponente sofort nutzt. `multipleProp` und `requiredProp` gibt es schon.\n - G3c.2: `kol-input-file` erbt direkt von `BaseFormFieldWebComponent`. Der Browse-Button bleibt `KolButtonWcTag`, weil die Themes `.kol-input-container__button .kol-button` als Vorfahr-Beziehung selektieren (G7). Die Drag-Listener hängen dann als JSX-Listener am Container; die Legacy-Komponente hängt sie in `componentDidLoad` an und entfernt sie nie.\n\n- Zusätzliche Abnahme: `table-settings` pixelgleich; `reset()` bei date und file; Flag an und aus im Pixel-Gate.\n\n### G4 – Auswahl-Controls: checkbox → radio (#9576, #9583)\n\nNur diese beiden nutzen den FieldControl-Stack statt InputContainer und teilen `InputCheckboxRadioController`.\n\n- G4 besteht aus fünf PRs:\n\n ```\n G3 ─► G4.0 Testlücken ─► G4.1 options ─► G4.2 FieldControl-/Checkbox-/Radio-FCs + fieldset ─► G4.3 checkbox ─► G4.4 radio\n ```\n\n - G4.0: Snapshots für checkbox (ohne Namen, `_required`, `_value` als String und Objekt, eigene `_icons`, `_labelAlign: 'left'` mit `_hideLabel`, indeterminate als Switch) und radio (ausgewählte Option, ohne Namen, Gruppe `_disabled`, `_required`, `_hideLabel`, Option mit `hint`, Objektwert, Label als Zahl). e2e für die Pfeiltasten-Navigation von radio, `focus()`/`click()` sowie `getValue()`, den `onInput`-Wert `null` beim Abwählen (für `table-settings`) und das Löschen von `_indeterminate` bei checkbox. Befunde, die die Migration 1:1 übernimmt: #11114.\n - G4.1: `options`-Prop und `fillKeyOptionMap` ziehen aus `input-radio/controller.ts` nach `form-field/options.ts`; G5 braucht beides ebenfalls.\n - G4.2: FieldControlFC, CheckboxFC und RadioFC, dazu der `fieldset`-Wurzelknoten: `BemRootNodeFC` und `FormFieldFC` bekommen `component: 'div' | 'fieldset'`, das Label eine `legend`-Variante. Die alten FCs werden Adapter, damit Hydrate-Snapshot und Pixel-Gate die neuen sofort prüfen.\n - G4.3 und G4.4: die beiden Felder erben direkt von `BaseFormFieldWebComponent`; `InputCheckboxRadioController` wird aufgelöst.\n\n- Risiken: Theme-SCSS der Checkbox (300 LOC, verschachtelte Varianten); `indeterminate` nur als Property; Formularwert bei checked/unchecked; Objektwerte, Tastatur- und Fokus-Navigation bei Radio.\n- Zusätzliche Abnahme: alle drei Checkbox-Varianten je Theme; Tastatur-E2E für Radio; `table-settings` pixelgleich.\n\n### G5 – Listen: select → combobox + single-select (#9594, #9569, #9595)\n\n- select: `BaseSelectWebComponent` für `kol-select` und das Übergangs-Tag `kol-select-wc` (DD16, Übergangsmuster `shadow: false`).\n- combobox und single-select: gemeinsame Basis oder ein `ListboxBehavior` für Tastatur, open/close und focusin/out. `@Listen`-Handler folgen der Event-Handler-Policy.\n- Risiken: Options-Sync des versteckten `<select multiple>`; `pagination` hängt am Light DOM von `kol-select-wc`; `:has()`-Selektoren im CustomSuggestions-SCSS.\n- Zusätzliche Abnahme: `pagination` pixelgleich; Tastatur- und Maus-E2E für combobox und single-select; bekannte Bugs bestehen nachweislich unverändert weiter oder wurden vorher gefixt.\n- Schnitt: G5.0 Testlücken → G5.1 select-Fundament (Props, Wert-Helfer, `SelectFC`, Legacy-FCs als Adapter) → G5.2 `kol-select` und `kol-select-wc` → G5.3 `BaseListboxWebComponent` und `kol-combobox` → G5.4 `kol-single-select`.\n- G5.0: Die select-Snapshots registrieren `kol-select` und `kol-select-wc`, damit sie das native Select enthalten. Neue e2e-Tests „Keyboard and mouse“ (combobox, single-select) und „Value“ (select). Befunde in #11124 und #10841.\n- `kol-select` rendert das FC direkt in seinem Shadow DOM, ohne das innere `kol-select-wc`. Diese DOM-Änderung wird in G5.2 einzeln abgenommen. Als eigenständiges Formularfeld setzt `kol-select` `_touched` und `_value` wie alle migrierten Felder; damit ist #11014 behoben. Nach G5.4 überträgt `kol-select` auch einen Einzelwert in `FormData` und in das `_syncValueBySelector`-Ziel (#11015): Ein `<select>`-Ziel erhält je Wert eine gewählte Option, ein anderes Ziel den Wert als String, mit `_multiple` als JSON.\n- `kol-single-select` liest `_value` und `_rows` ungeprüft wie zuvor: Jeder Wert von `_value`, auch `undefined`, ist die Auswahl, und `_rows` ist der CSS-Wert `--visible-options`. Der Abgleich des Eingabetexts mit den Labels beim Verlassen des Felds (#10501, #10617) bleibt bis zu einem eigenen Fix.\n\n### G6 – Rückbau\n\nGelöscht wird, sobald der letzte Import weg ist. Veröffentlichte Schema-Typen bleiben stehen: die `*Watches`-Typen und die `validate*`-Funktionen aus `schema/index.ts` sind Teil der veröffentlichten API (der `react-hook-form-adapter` importiert aus `dist/types/schema`), ihr Entfernen wäre ein eigener Breaking Change. In `functional-components/` bleiben `Heading` (alert, card, collapsible) und `ToastItem` (toaster).\n\n| Zeitpunkt | Was gelöscht wird |\n| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| nach G2 | erledigt in G2: `utils/counter-dom-updater.ts`, `InputPasswordController`, `InputTextEmailController`, `InputTextController`, `TextAreaStateWrapper`, alte `inputs/TextArea` |\n| nach G3a | erledigt in G3a: `InputNumberController`, `InputRangeController`, `InputIconController.isNumberString` |\n| nach G3b | erledigt in G3b: `InputDateController`, `InputIconController.validateNumber`/`parseToNumber` |\n| nach G3c | erledigt in G3c: `InputFileController` |\n| nach G4 | erledigt in G4: `InputCheckboxController`, `InputRadioController`/`InputCheckboxRadioController`, `Checkbox`-/`Radio`-/`FieldControlStateWrapper`, altes `FieldControl`, alte `inputs/Checkbox`/`inputs/Radio` |\n| nach G5 | erledigt in G5.2–G5.4: `SelectController`, `ComboboxController`, `SingleSelectController`, `SelectStateWrapper`, `NativeSelect`/`NativeOption(List)`, alte `CustomSuggestionsOption(sGroup)`; `kol-select-wc` in G7.7, nachdem `kol-pagination` das Select-Feld in G7.6 direkt rendert |\n| final | erledigt: `@deprecated/input/*` (`InputController`, `InputIconController`), `input-adapter-leanup/`, `functional-component-wrappers/` inkl. `getRenderStates`, die Adapter aus G1.3, die alten FormField-/Input-FCs in `functional-components/` (`FormField*`, `InputContainer`, `InputAdornment`, `IconButton`, `inputs/`, `Suggestions`, `Button`) |\n\n### G7 – Folge-Epics (außerhalb dieser Migration)\n\n- ✅ Die Übergangs-Tags (`kol-button-wc`, `kol-link-wc`, `kol-popover-button-wc`, `kol-select-wc`, `kol-dialog-wc`, `kol-alert-wc`, `kol-table-settings-wc`) sind durch die Functional Components und Items ersetzt und gelöscht (G7.1–G7.7, #11167, #11172, #11174–#11178). `kol-tooltip-wc` bleibt als einzige `-wc`-Komponente erhalten: weiterhin deprecated und ausdrücklich nur für DESYBRI.\n- Umstieg auf natives `formAssociated` mit ElementInternals (Verhaltensänderung, eventuell Breaking).\n- BEM-Bereinigung mit CLI-Tasks `ScssRename*` und Migrationsguide für Custom-Themes.\n\n## Offene Fragen für die Detailpläne\n\n1. ~~Sind die Shell-Adapter (alte FC → neue FC) als Zwischenschicht akzeptabel? (G1.3)~~ Entschieden: ja, siehe G1.3.\n2. ~~ID-Strategie: bisherige Erzeugung für Snapshot-Parität oder DD12 `createUniqueId`? (G1.4)~~ Kein Konflikt: Legacy nutzt bereits `createUniqueId` und `createRelatedUniqueId`. Die Basis-ID wird einmal pro Instanz als `@State()` erzeugt.\n3. ~~`_touched` als `@State` oder als Render-Prop? (G1.4)~~ Entschieden: Render-Prop. `_touched` bleibt `@Prop({ mutable: true, reflect: true })`, der Blur-Handler schreibt die Prop (Vorbild `_open` in `kol-details`).\n4. ~~`_on`: eine gemeinsame Callback-Prop oder typisiert pro Feld? (G1.1)~~ Entschieden: gemeinsam, alle Felder deklarieren `InputTypeOnDefault`.\n5. ~~SSR-Absturz von `attachInternals(undefined)` 1:1 übernehmen oder mit eigenem PR über einen Guard absichern? (G1.2)~~ Entschieden: 1:1 übernehmen, Fix als eigener PR nach G1.2 (#11034). Ursache ist nicht ein leeres `@Element()`: In mock-doc greift `instanceof Element` in `findHostWithShadowRoot` nicht. Betroffen sind im SSR die inneren `kol-button-wc`/`kol-popover-button-wc` und mit `serializeShadowRoot: 'scoped'` alle Legacy-Felder.\n6. ~~Verhaltensverträge in Jest oder in Playwright? (G0)~~ Entschieden: Playwright, siehe G0.\n7. ~~Namen der Input-Props für min/max/step. (G3)~~ Entschieden: `inputMinProp`, `inputMaxProp` und `stepProp`, analog zu `horizontalIconsProp` (G1.1).\n8. ~~`kol-select-wc` als Übergangs-Tag behalten oder `pagination` direkt auf das FC umstellen? (G5)~~ Entschieden: `kol-select` rendert das FC direkt. `kol-select-wc` bleibt als Übergangs-Tag für `pagination`, mit derselben Basis; die Ablösung braucht Theme-Änderungen (G7). Umgesetzt in G7.6 und G7.7.\n9. ~~combobox und single-select: gemeinsame DD16-Basis oder `ListboxBehavior`? (G5)~~ Entschieden: gemeinsame Basis `BaseListboxWebComponent extends BaseFormFieldWebComponent`, wie `BaseTextInputWebComponent` in G2.\n10. ~~#10501 und #10617 vor oder nach der Migration fixen? (G5)~~ Entschieden: nach der Migration, als eigener PR auf dem migrierten Code. Die Migration übernimmt das Verhalten 1:1.\n\n## Grundlagen\n\n- `packages/components/src/components/_skeleton/ARC42.md`\n- Skill `.claude/skills/migrate-to-skeleton/` (inkl. `reference/patterns.md`, `reference/pitfalls.md`)\n- Skill `.claude/skills/zero-visual-delta-handoff/`\n",
|
|
417
|
+
"code": "# Migrationsplan: Formularfelder auf Skeleton\n\nÜbergreifender Plan für die Skeleton-Migration der 14 Formularfelder von `kol-combobox` bis `kol-textarea` (Epic #9559). Er schneidet die Felder in Gruppen, legt das gemeinsame Fundament fest und ordnet die Arbeit in parallele Spuren. Jede Gruppe erhält vor der Umsetzung einen eigenen Detailplan.\n\nStand: 27.09.2026, `@public-ui/components` 4.5.0-rc.0.\n\n## Ausgangslage\n\nVor der Migration lief keines der 14 Felder auf Skeleton. Der Legacy-Stack besteht aus:\n\n- Controller-Kette `AssociatedInputController → ControlledInputController → InputController → InputIconController → Feld-Controller`\n- State-Wrapper in `functional-component-wrappers/`, die die alten FCs in `functional-components/` rendern\n- Validatoren aus `schema/props/`\n\nAus dem Formularumfeld ist bisher nur `kol-form` auf Skeleton umgestellt.\n\n| Feld | LOC `shadow.tsx` | Render-Stack heute | Besonderheit |\n| -------------------- | --------------------------- | ------------------------------------------- | --------------------------------------------------------------- |\n| `kol-input-color` | 380 | FormField + InputContainer + Input („Trio\") | dünnstes Feld, kein `_required` |\n| `kol-input-email` | 489 | Trio | Controller erbt von Text → Password, Counter |\n| `kol-input-password` | 511 | Trio + IconButton (`KolButtonWcTag`) | `_visibilityToggle`, Basisklasse für Text und Email |\n| `kol-input-text` | 620 | Trio + Clear-Button | `_type`, Selection-API-Methoden |\n| `kol-textarea` | 498 | FormField + InputContainer + TextArea | `_adjustHeight`, `_resize`, `_rows`, Counter |\n| `kol-input-number` | 551 | Trio + Step-Buttons | Feature-Flag `inputNumberButtons`, genutzt von `table-settings` |\n| `kol-input-range` | 499 | 2× Input (range + number) + Suggestions | min/max/step, zwei synchrone Inputs |\n| `kol-input-date` | 513 (+ 219 Controller) | Trio | Date↔ISO, 5 `_type`s, `reset()` |\n| `kol-input-file` | 450 | Trio + Browse-Button (`KolButtonWcTag`) | kein `_value`, FileList, `_accept`, Drag & Drop, `reset()` |\n| `kol-input-checkbox` | 457 | FormField + FieldControl + Checkbox | Varianten default/switch/button, genutzt von `table-settings` |\n| `kol-input-radio` | 458 | FormField (fieldset) + FieldControl + Radio | `_options`, `_orientation`, alte Utils `element-click`/`-focus` |\n| `kol-select` | 222 + 404 (`kol-select-wc`) | FormField + InputContainer + NativeSelect | `pagination` rendert `kol-select-wc` direkt |\n| `kol-combobox` | 756 | Trio + CustomSuggestions + `@Listen` | Listbox, nahezu Zwilling von single-select |\n| `kol-single-select` | 849 | Trio + CustomSuggestions + `@Listen` | größtes Feld, offene Bugs #10501/#10617 |\n\n## Rahmenbedingungen\n\n- **Zero visual delta, BEM bleibt.** DOM und Klassen (`.kol-form-field`, `.kol-input-container`, `.kol-field-control` …) bleiben byte-identisch. Themes werden nicht angefasst, es gibt keinen CLI-/SCSS-Migrations-Task. Das Pixel-Gate verlangt 0 Diffs pro Theme.\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",
|
|
418
427
|
"kind": "doc"
|
|
419
428
|
},
|
|
420
429
|
{
|
|
@@ -476,7 +485,7 @@
|
|
|
476
485
|
"name": "MIGRATION",
|
|
477
486
|
"description": "New major versions of KoliBri are developed with the aim of simplifying maintenance and support and promoting further development.",
|
|
478
487
|
"path": "MIGRATION.md",
|
|
479
|
-
"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",
|
|
480
489
|
"kind": "doc"
|
|
481
490
|
},
|
|
482
491
|
{
|
|
@@ -485,7 +494,7 @@
|
|
|
485
494
|
"name": "MIGRATION.de",
|
|
486
495
|
"description": "Neue Major-Versionen von KoliBri werden mit dem Ziel entwickelt, die Wartung und Pflege zu vereinfachen und Weiterentwicklung zu fördern.",
|
|
487
496
|
"path": "MIGRATION.de.md",
|
|
488
|
-
"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",
|
|
489
498
|
"kind": "doc"
|
|
490
499
|
},
|
|
491
500
|
{
|
|
@@ -515,13 +524,22 @@
|
|
|
515
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",
|
|
516
525
|
"kind": "doc"
|
|
517
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
|
+
},
|
|
518
536
|
{
|
|
519
537
|
"id": "doc/README",
|
|
520
538
|
"group": "docs",
|
|
521
539
|
"name": "README",
|
|
522
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…",
|
|
523
541
|
"path": "README.md",
|
|
524
|
-
"code": "# Welcome to KoliBri\n\n[](https://www.npmjs.com/package/@public-ui/components)\n[](https://github.com/public-ui/kolibri/blob/develop/LICENSE)\n[](https://www.npmjs.com/package/@public-ui/components)\n[](https://github.com/public-ui/kolibri/issues)\n[](https://github.com/public-ui/kolibri/pulls)\n[](https://bundlephobia.com/result?p=@public-ui/components)\n\n[](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[](https://www.npmjs.com/package/@public-ui/components)\n[](https://github.com/public-ui/kolibri/blob/develop/LICENSE)\n[](https://www.npmjs.com/package/@public-ui/components)\n[](https://github.com/public-ui/kolibri/issues)\n[](https://github.com/public-ui/kolibri/pulls)\n[](https://bundlephobia.com/result?p=@public-ui/components)\n\n[](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",
|
|
525
543
|
"kind": "doc"
|
|
526
544
|
},
|
|
527
545
|
{
|
|
@@ -542,6 +560,15 @@
|
|
|
542
560
|
"code": "# Security/Sicherheit\n\n## CVE Overview\n\nSee [CVE_OVERVIEW.md](./CVE_OVERVIEW.md) for an automated overview of security vulnerabilities across all KoliBri versions.\n\n## Report security issues (EN)\n\nIf you believe you have found a security vulnerability in our project, we encourage you to let us know immediately. We will investigate all legitimate reports and do our best to fix the problem quickly.\n\nContact: [kolibri@itzbund.de](mailto:kolibri@itzbund.de)\n\n## Melden von Sicherheitsproblemen (DE)\n\nWenn Sie glauben, dass Sie eine Sicherheitslücke in unserm Projekt gefunden haben, empfehlen wir Ihnen, uns dies umgehend mitzuteilen. Wir werden alle legitimen Meldungen untersuchen und unser Bestes tun, um das Problem schnell zu beheben.\n",
|
|
543
561
|
"kind": "doc"
|
|
544
562
|
},
|
|
563
|
+
{
|
|
564
|
+
"id": "doc/SKELETON_AUDIT_REPORT",
|
|
565
|
+
"group": "docs",
|
|
566
|
+
"name": "SKELETON_AUDIT_REPORT",
|
|
567
|
+
"description": "Datum: 2026-06-02 Status: 🚫 Build-Blockade erkannt (Phase 0) — Audit trotzdem vollständig durchgeführt Umfang: Alle Skeleton-bezogenen Implementierungen Effort: High (systematische Analyse aller Komponenten)",
|
|
568
|
+
"path": "SKELETON_AUDIT_REPORT.md",
|
|
569
|
+
"code": "# Skeleton Implementation Audit Report\n\n**Datum:** 2026-06-02 \n**Status:** 🚫 Build-Blockade erkannt (Phase 0) — Audit trotzdem vollständig durchgeführt \n**Umfang:** Alle Skeleton-bezogenen Implementierungen \n**Effort:** High (systematische Analyse aller Komponenten)\n\n---\n\n## Executive Summary\n\n### Übersicht\n\nDie Skeleton-Implementierungen im Projekt folgen einem **konsistenten Pattern**, sind aber durch mehrere **Mängel** gekennzeichnet:\n\n**Gefundene Implementierungen:**\n\n1. `_skeleton/web-components/skeleton/` — Template-Komponente (KolSkeleton)\n2. `_skeleton/web-components/click-button/` — Button-Komponente im Template\n3. `internal/functional-components/skeleton/` — Skeleton FC + Controller\n4. `internal/functional-components/click-button/` — ClickButton FC + Controller\n\n**Build-Status (Phase 0):** 🚫 **BLOCKADE**\n\n- TypeScript-Fehler in `KolFocusOptions` ↔ native `FocusOptions` (systemisch)\n- Build bricht — verhindert Validierung auf echtem Build\n\n**Konsistenz-Grade:**\n\n- ✅ **Hoch:** Controller-Pattern, Props-Handling, JSDoc-Struktur\n- 🟡 **Mittel:** Event-Propagation, Type-Safety, Error-Handling\n- 🚫 **Niedrig:** Memory-Leak-Risiken, Testing-Abdeckung, Focus-Management\n\n---\n\n## 🔍 Detaillierte Analysen\n\n### 1. KolSkeleton Component (`_skeleton/web-components/skeleton/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/components/_skeleton/web-components/skeleton/component.tsx`\n\n#### ✅ Stärken\n\n- Korrekte Stencil-Dekoration (`@Component`, `@Prop`, `@Event`, `@Method`, `@Listen`, `@Watch`)\n- JSDoc-Kommentare auf allen `@Prop`, `@Event`, `@Method` vorhanden\n- Korrektes Lifecycle-Pattern (componentWillLoad, componentDidLoad, disconnectedCallback)\n- Typsicher: `SkeletonApi` zentral definiert\n\n#### 🔴 Critical Issues\n\n**1. Fehlerhafte Focus-Delegation (Line 22)**\n\n```typescript\n@Method()\n@ctrlFocus('ctrl')\npublic async focus(options?: KolFocusOptions): Promise<void> {}\n```\n\n**Problem:**\n\n- `@ctrlFocus` Decorator wird verwendet, aber `delegateFocus` ist der aktuelle Standard (lt. memory: focus-delegation-pattern.md)\n- `KolFocusOptions` ist nicht kompatibel mit nativer `FocusOptions` → **Build-Blockade**\n- Decorator-Pattern sollte `delegateFocus('ref')` sein (wie in ClickButton)\n\n**Priorität:** 🔴 **HIGH** (Breaking + systemisch) \n**Fix:** Focus-Methode korrekt implementieren wie in `ClickButton`\n\n**2. Memory Leak durch `.bind(this)` in handleClick (Line 59)**\n\n```typescript\n@Listen('keydown')\npublic handleKeyDown(event: KeyboardEvent): void {\n // ...\n this.ctrl.handleClick(); // ✅ OK — direkt, kein .bind()\n}\n```\n\n**Positive Beobachtung:** KolSkeleton nutzt `this.ctrl.handleClick()` korrekt (kein `.bind()`).\n\n**3. Fehlende Error-Handling bei Event-Emits (Lines 84-86)**\n\n```typescript\nthis.ctrl.setOnLoadedCallback((count: number) => {\n\tthis.loaded.emit(count); // Kein try-catch\n});\n```\n\n**Problem:** Wenn `emit()` wirft → Component crashed still. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** `try-catch` um Event-Emission oder defensive Implementierung\n\n**4. Window-Listener ohne Cleanup (Line 73-76)**\n\n```typescript\n@Listen('keydown', { target: 'window' })\npublic onKeydown(event: KeyboardEvent): void {\n this.ctrl.onKeydown(event);\n}\n```\n\n**Problem:** `@Listen` mit `target: 'window'` wird automatisch von Stencil bereinigt, aber **dokumentation fehlt**. \n**Priorität:** 🟡 **MEDIUM** (Doku-Mangel) \n**Fix:** JSDoc-Kommentar: \"Auto-cleaned by Stencil\"\n\n#### 🟡 High Issues\n\n**5. Type-Assertion in SkeletonFC Props (Line 105)**\n\n```typescript\nname={this.ctrl.getRenderProp('name')} // ✅ Typsicher\n```\n\n**Status:** OK — keine Assertions.\n\n**6. Fehlende JSDoc auf State-Feldern (Lines 46-53)**\n\n```typescript\n@State()\npublic count: number = 0;\n\n@State()\npublic label: string = 'Label';\n```\n\n**Problem:** State-Felder ohne JSDoc, obwohl sie durch Events exponiert werden. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentare hinzufügen\n\n---\n\n### 2. KolClickButton Component (`_skeleton/web-components/click-button/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/components/_skeleton/web-components/click-button/component.tsx`\n\n#### ✅ Stärken\n\n- Minimal, fokussiert (Single Responsibility)\n- Korrekte `delegateFocus` Implementierung (Line 37)\n- Saubere Ref-Handling mit `createCtaRef`\n- Props-Binding korrekt\n\n#### 🚫 Critical Issues\n\n**1. Focus-Options Type-Mismatch (Line 40)**\n\n```typescript\n@Method()\n@delegateFocus('buttonRef')\npublic async focus(options?: KolFocusOptions): Promise<void> {}\n```\n\n**Problem:** Decorator erwartet `KolFocusOptions`, aber `delegateFocus` nutzt `setFocus()` welches mit `FocusOptions` arbeitet. \n**Impact:** Build-Fehler in `accordion/shadow.tsx:48` (type constraint violation)\n\n**Priorität:** 🔴 **HIGH** (systemisch) \n**Fix:** Type-Signature anpassen oder Decorator aktualisieren\n\n**2. Fehlende JSDoc auf Prop (Lines 23-26)**\n\n```typescript\n/**\n * Sets the label of the click button component.\n */\n@Prop()\npublic _label!: string;\n```\n\n**Status:** ✅ OK — JSDoc vorhanden\n\n#### 🟡 High Issues\n\n**3. onClick Handler Type-Safety (Line 57)**\n\n```typescript\nhandleClick={this.ctrl.handleClick}\n```\n\n**Problem:** `this.ctrl.handleClick` wird direkt passed — wenn Signature ändert, bricht es still. \n**Priorität:** 🟡 **MEDIUM** \n**Fix:** Arrow-Function: `handleClick={() => this.ctrl.handleClick()}`\n\n---\n\n### 3. SkeletonController (`internal/functional-components/skeleton/controller.ts`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/skeleton/controller.ts`\n\n#### 🔴 Critical Issues\n\n**1. Memory Leak: setInterval ohne Cleanup-Dokumentation (Lines 63-68)**\n\n```typescript\nprivate startLoadedEventInterval(): void {\n this.intervalId = setInterval(() => {\n this.emitLoaded(this.getState?.('count') ?? 0);\n }, 2000);\n}\n```\n\n**Problem:**\n\n- ✅ `intervalId` wird in `destroy()` gelöscht (Line 86)\n- 🚫 **Aber:** `destroy()` wird NUR in `disconnectedCallback()` aufgerufen\n- 🚫 **Große Lücke:** Wenn Component nicht destruktiv entfernt wird (z.B. `display: none`), läuft Interval endlos\n- 🚫 **Kein Dokumentation** warum `destroy()` nötig ist\n\n**Priorität:** 🔴 **CRITICAL** (Speicherleck in Production) \n**Fix:**\n\n```typescript\n// JSDoc dokumentieren\n/**\n * Startet den Loaded-Event-Interval.\n * WICHTIG: destroy() muss in disconnectedCallback() aufgerufen werden,\n * sonst läuft der Interval im Hintergrund.\n */\n```\n\n**2. Unzureichende State-Initialisierung (Lines 37-39)**\n\n```typescript\npublic toggle(): void {\n this.setState('show', !(this.getState?.('show') ?? false));\n}\n```\n\n**Problem:** `getState?.('show')` kann `undefined` sein — `?? false` ist defensiv, aber:\n\n- Default sollte in BaseController oder State-Definition sein, nicht hier\n- Keine Konsistenz mit `count` (Line 51 in component.tsx)\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** State-Defaults zentral definieren\n\n**3. Console.log statt Log.debug (Line 44)**\n\n```typescript\nconsole.log('Show should be toggled');\n```\n\n**Problem:** Inkonsistent mit anderen Zeilen die `Log.debug()` nutzen (z.B. SkeletonFC). \n**Priorität:** 🟢 **LOW** \n**Fix:** `Log.debug()` verwenden\n\n**4. Keine Error-Handling in emitLoaded (Lines 70-77)**\n\n```typescript\nprivate emitLoaded(count: number): void {\n if (this.onLoadedCallback) {\n this.onLoadedCallback(count); // Kein try-catch\n }\n}\n```\n\n**Problem:** Wenn Callback wirft → Component-State wird inkonsistent. \n**Priorität:** 🟡 **MEDIUM**\n\n#### 🟡 High Issues\n\n**5. ClickButtonController Instanz ohne State-Zugriff (Line 18)**\n\n```typescript\nthis.clickButtonCtrl = new ClickButtonController(BaseWebComponent.stateLess);\n```\n\n**Problem:** `stateLess` ist korrekt, aber:\n\n- Keine Dokumentation **warum** ClickButton stateless\n- Wenn jemand State hinzufügt → silentes Bug\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentar\n\n---\n\n### 4. ClickButtonController (`internal/functional-components/click-button/controller.ts`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/click-button/controller.ts`\n\n#### ✅ Stärken\n\n- Minimal, einfach zu verstehen\n- Korrekte Props-Handling (`watchLabel`)\n- Fokus-Delegation delegiert korrekt an `setFocus()`\n\n#### 🔴 Critical Issues\n\n**1. Memory Leak durch `.bind(this)` auf Line 32**\n\n```typescript\npublic handleClick = (): void => {\n console.log(this, this.buttonRef, 'button clicked');\n};\n```\n\n**Status:** ✅ OK — Arrow-Function (kein `.bind()`)\n\n**2. Type-Safety in setButtonRef (Line 37)**\n\n```typescript\npublic setButtonRef = (element?: HTMLButtonElement): void => {\n this.buttonRef = element;\n};\n```\n\n**Status:** ✅ OK — typsicher\n\n#### 🟡 High Issues\n\n**3. Console.log statt Log (Line 34)**\n\n```typescript\nconsole.log(this, this.buttonRef, 'button clicked');\n```\n\n**Problem:**\n\n- Nicht über Log-System\n- Logs `this` (ganze Controller-Instanz) → potenzielle Datenexposition\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** `Log.debug()` mit spezifischen Values\n\n**4. Fehlende JSDoc auf focus() (Line 22)**\n\n```typescript\npublic async focus(options?: KolFocusOptions): Promise<void> {\n return setFocus(this.buttonRef, options);\n}\n```\n\n**Problem:**\n\n- `KolFocusOptions` Type-Mismatch (systemisch)\n- Keine Dokumentation dass async ist\n\n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n### 5. SkeletonFC (`internal/functional-components/skeleton/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/skeleton/component.tsx`\n\n#### ✅ Stärken\n\n- Functional Component sauber\n- BEM-Klasse-Generierung konsistent\n- Props korrekt destructured\n\n#### 🟡 High Issues\n\n**1. Event-Propagation nicht dokumentiert (Line 15)**\n\n```typescript\nexport const SkeletonFC: FC<FunctionalComponentProps<SkeletonApi>> = (props) => {\n const { count, label, name, show, handleClick, refButton } = props;\n```\n\n**Problem:**\n\n- Event `onLoaded`, `onRendered` werden in Props passed, aber **nicht in FC genutzt**\n- Diese Events werden in KolSkeleton component direkt emittet, nicht über FC\n- **Inkonsistenz:** Props definieren Events, aber FC nutzt sie nicht\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** Dokumentation oder Props bereinigen\n\n**2. Props-Typ unsicher (Line 15)**\n\n```typescript\nFunctionalComponentProps<SkeletonApi>;\n```\n\n**Problem:** `FunctionalComponentProps<T>` ist zu allgemein — was genau wird erwartet? \n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n### 6. ClickButtonFC (`internal/functional-components/click-button/component.tsx`)\n\n**Dateipfad:** `/packages/components/src/internal/functional-components/click-button/component.tsx`\n\n#### ✅ Stärken\n\n- Sehr sauber, minimal\n- onClick Handler korrekt\n- BEM-Klassen konsistent\n\n#### 🟡 High Issues\n\n**1. onKeyDown PreventDefault ohne Dokumentation (Line 13)**\n\n```typescript\nonKeyDown={(event) => event.preventDefault()}\n```\n\n**Problem:**\n\n- **Warum wird keydown preventDefaultet?** Keine Dokumentation\n- Das ist ungewöhnlich für ein Button-Element\n- Könnte Accessibility-Problem sein\n\n**Priorität:** 🟡 **MEDIUM** \n**Fix:** JSDoc-Kommentar erklären warum\n\n---\n\n### 7. Testing & Snapshots\n\n#### Skeleton Snapshot Tests (`_skeleton/web-components/skeleton/snapshot.spec.tsx`)\n\n```typescript\nexecuteSnapshotTests<SkeletonSnapshotProps>(KOL_SKELETON_TAG, [KolSkeleton], [{ _name: 'Ada Lovelace' }, { _name: '' }]);\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Two snapshot variants tested\n- 🚫 **Fehlt:**\n - `show=true` vs `show=false` variant\n - `count` variations\n - Edge case: sehr lange Name\n - **State wird nicht tested** (nur Props)\n\n**Priorität:** 🟡 **MEDIUM** \n**Empfehlung:** Snapshots erweitern\n\n#### ClickButton Snapshot Tests (`_skeleton/web-components/click-button/snapshot.spec.tsx`)\n\n```typescript\nexecuteSnapshotTests<ClickButtonSnapshotProps>(KOL_CLICK_BUTTON_TAG, [KolClickButton], [{ _label: 'Click me' }, { _label: 'Submit form' }]);\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Two label variants\n- 🚫 **Fehlt:**\n - Edge cases (empty label, very long label)\n - Disabled state (if supported)\n - Focus state\n\n**Priorität:** 🟡 **MEDIUM**\n\n#### E2E Tests (`_skeleton/web-components/click-button/interaction.e2e.ts`)\n\n```typescript\ntest('should call handleClick when clicked', async ({ page }) => {\n\tconst logMessages: string[] = [];\n\tpage.on('console', (msg) => {\n\t\tlogMessages.push(msg.text());\n\t});\n\tawait page.getByRole('button', { name: 'Click' }).click();\n\texpect(logMessages.length).toBeGreaterThan(0);\n});\n```\n\n**Status:** 🟡 **Minimal**\n\n- ✅ Using accessibility role (correct)\n- 🚫 **Fehlt:**\n - Keyboard interaction test (Space, Enter)\n - Focus test\n - Event-Listener test (addEventListener pattern)\n - **Log assertion fragile:** `logMessages.length > 0` ist zu vage\n\n**Priorität:** 🟡 **MEDIUM** \n**Empfehlung:** E2E-Tests erweitern nach team3 Kriterien\n\n---\n\n### 8. API & Type Definitions\n\n#### SkeletonApi (`internal/functional-components/skeleton/api.tsx`)\n\n```typescript\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tListeners: { keydown: KeyboardEvent };\n\t\tMethods: { focus: (options?: KolFocusOptions) => void; toggle: () => void };\n\t\tRefs: { button: HTMLButtonElement };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n**Status:** 🟡 **Konsistent, aber Lücken**\n\n- ✅ Alle Props typsicher\n- ✅ Alle Emitters definiert\n- 🚫 **Probleme:**\n - `KolFocusOptions` ist problematisch (systemisch)\n - `Listeners` mit `keydown` ist ungewöhnlich — sollte über Events handled werden?\n - `Callbacks: click` wird nie genutzt (nur `handleClick` Arrow-Funktion)\n\n**Priorität:** 🟡 **MEDIUM**\n\n---\n\n## 📊 Konsistenz-Analyse\n\n### Pattern Konsistenz (Web Components ↔ Functional Components)\n\n| Aspekt | KolSkeleton | KolClickButton | Standard | Status |\n| ------------------- | ------------------------------------------------------------ | --------------------- | --------------- | ----------- |\n| **Component-Dekor** | ✅ `@Component` | ✅ `@Component` | — | ✅ OK |\n| **Props** | ✅ `@Prop` + `@Watch` | ✅ `@Prop` + `@Watch` | — | ✅ OK |\n| **Events** | ✅ `@Event` | 🚫 Keine | Required | 🔴 MISMATCH |\n| **Methods** | ✅ `@Method` | ✅ `@Method` | — | ✅ OK |\n| **Listen** | ✅ `@Listen` | 🚫 Keine | Optional | 🟡 OK |\n| **State** | ✅ `@State` | 🚫 Keine | Optional | ✅ OK |\n| **JSDoc** | ✅ `@Prop/@Event` | ✅ `@Prop/@Method` | Pflicht | ✅ OK |\n| **Focus** | 🔴 `@ctrlFocus` | ✅ `@delegateFocus` | `delegateFocus` | 🔴 MISMATCH |\n| **Lifecycle** | ✅ componentWillLoad, componentDidLoad, disconnectedCallback | ✅ componentWillLoad | — | ✅ OK |\n\n**Konsistenz-Probleme:**\n\n- 🔴 **CRITICAL:** Focus-Pattern unterschiedlich (ctrlFocus vs delegateFocus)\n- 🔴 **CRITICAL:** KolSkeleton hat Events, KolClickButton nicht\n- 🚫 **Wird nicht repariert durch Template** (Template ist Guide, nicht Copy-Paste)\n\n---\n\n## 🔴 Mängelliste (priorisiert)\n\n### 🔴 CRITICAL (Blocker)\n\n#### 1. Focus-Type Mismatch (systemisch)\n\n**Files:** Alle Komponenten mit `delegateFocus` oder `ctrlFocus` \n**Issue:** `KolFocusOptions` ↔ native `FocusOptions` Inkompatibilität \n**Impact:** Build bricht \n**Fix:** Type-Alignment in `KolFocusOptions` ← `FocusOptions` \n**Effort:** High (systemisch, viele Dateien betroffen)\n\n#### 2. KolSkeleton: Fehlerhafte Focus-Decoration (Line 22)\n\n**File:** `_skeleton/web-components/skeleton/component.tsx` \n**Issue:** `@ctrlFocus('ctrl')` verwenden, aber sollte `delegateFocus('ref')` sein \n**Fix:** Pattern wie ClickButton übernehmen \n**Effort:** Low\n\n#### 3. SkeletonController: Memory Leak (Interval ohne Cleanup-Dokumentation)\n\n**File:** `internal/functional-components/skeleton/controller.ts:63-68` \n**Issue:** `setInterval()` läuft im Hintergrund wenn Component nicht destruktiv entfernt \n**Fix:** JSDoc-Dokumentation + Verify Cleanup-Path \n**Effort:** Low\n\n---\n\n### 🟡 HIGH (Quality / Safety)\n\n#### 4. Event-Emission ohne Error-Handling\n\n**Files:**\n\n- `_skeleton/web-components/skeleton/component.tsx:84`\n- `internal/functional-components/skeleton/controller.ts:74`\n\n**Issue:** `emit()` kann werfen, kein try-catch \n**Fix:** `try-catch` um Event-Emits \n**Effort:** Low\n\n#### 5. KolClickButton: onClick Handler Type-Safety (Line 57)\n\n**File:** `_skeleton/web-components/click-button/component.tsx` \n**Issue:** `handleClick={this.ctrl.handleClick}` direkt passed — keine Arrow-Func \n**Fix:** `handleClick={() => this.ctrl.handleClick()}` \n**Effort:** Trivial\n\n#### 6. Console.log statt Log-System\n\n**Files:**\n\n- `internal/functional-components/skeleton/controller.ts:44`\n- `internal/functional-components/click-button/controller.ts:34`\n\n**Issue:** Nicht über Log-System, potenzielle Datenexposition \n**Fix:** `Log.debug()` mit spezifischen Values \n**Effort:** Trivial\n\n#### 7. ClickButtonFC: onKeyDown preventDefault ohne Dokumentation (Line 13)\n\n**File:** `internal/functional-components/click-button/component.tsx` \n**Issue:** **Warum preventDefault?** Keine Dokumentation — könnte A11y-Problem sein \n**Fix:** JSDoc erklären oder entfernen wenn nicht nötig \n**Effort:** Low\n\n#### 8. Missing JSDoc on State Fields\n\n**File:** `_skeleton/web-components/skeleton/component.tsx:46-53` \n**Issue:** `@State count`, `@State label`, `@State show` ohne JSDoc \n**Fix:** JSDoc-Kommentare hinzufügen \n**Effort:** Trivial\n\n#### 9. Window-Listener Stencil Auto-Cleanup nicht dokumentiert\n\n**File:** `_skeleton/web-components/skeleton/component.tsx:73` \n**Issue:** `@Listen('keydown', { target: 'window' })` — Auto-Cleanup Stencil-Feature nicht dokumentiert \n**Fix:** JSDoc-Kommentar \n**Effort:** Trivial\n\n---\n\n### 🟢 LOW (Code Quality)\n\n#### 10. State Default-Handling inkonsistent\n\n**File:** `internal/functional-components/skeleton/controller.ts:38` \n**Issue:** `getState?.('show') ?? false` — Defaults sollten zentral sein \n**Fix:** Refactor State-Defaults in BaseController \n**Effort:** Medium (aber nice-to-have)\n\n#### 11. SkeletonFC: Event-Props nicht genutzt\n\n**File:** `internal/functional-components/skeleton/component.tsx:15-31` \n**Issue:** `onLoaded`, `onRendered` werden in Props definiert, aber nicht in FC genutzt \n**Fix:** Dokumentation oder Props-Cleanup \n**Effort:** Low\n\n#### 12. Testing: Minimal Coverage\n\n**Files:**\n\n- `_skeleton/web-components/skeleton/snapshot.spec.tsx`\n- `_skeleton/web-components/click-button/snapshot.spec.tsx`\n- `_skeleton/web-components/click-button/interaction.e2e.ts`\n\n**Issue:** Nur Happy-Path getestet, Edge Cases + State Variations fehlen \n**Fix:** Tests erweitern (show=false, count variation, empty label, keydown events) \n**Effort:** Medium\n\n#### 13. ClickButtonController: Type-Generification fragile\n\n**File:** `internal/functional-components/click-button/controller.ts` \n**Issue:** `setButtonRef` erwartet `HTMLButtonElement` — was wenn in anderen Komponenten anders? \n**Fix:** Generische Type-Parameter oder Dokumentation \n**Effort:** Low (nice-to-have)\n\n---\n\n## 📋 Empfehlungen (Implementierungs-Roadmap)\n\n### Phase 1: Kritische Fixes (BLOCKING)\n\n1. **Fix Focus-Type Mismatch (systemisch)**\n - `KolFocusOptions` → `FocusOptions` Alignment\n - Oder: Bridge-Type erstellen\n - **Effort:** High\n - **Impact:** Unblocks Build\n\n2. **Fix KolSkeleton Focus-Decoration**\n - `@ctrlFocus` → `@delegateFocus('buttonRef')`\n - **Effort:** Low\n - **Impact:** Pattern-Konsistenz\n\n3. **Document SkeletonController Memory Leak**\n - JSDoc auf `startLoadedEventInterval()`\n - Verify `destroy()` Call in `disconnectedCallback()`\n - **Effort:** Trivial\n - **Impact:** Prevents Production Issue\n\n### Phase 2: Quality Fixes (Safety)\n\n4. Event-Emission Error-Handling\n - Try-catch um `emit()` calls\n - **Effort:** Low\n\n5. Console → Log-System\n - Replace `console.log` with `Log.debug`\n - **Effort:** Trivial\n\n6. JSDoc auf State-Feldern + Window-Listener\n - **Effort:** Trivial\n\n7. ClickButtonFC: preventDefault Dokumentation\n - **Effort:** Low\n\n### Phase 3: Test Expansion\n\n8. Snapshot Tests erweitern\n - Edge Cases (empty, very long, state variations)\n - **Effort:** Medium\n\n9. E2E Tests erweitern\n - Keyboard interactions (Space, Enter, Tab)\n - Focus management\n - Event-Listener pattern testing\n - **Effort:** Medium\n\n---\n\n## 🎯 Einheitliche Implementierungs-Standards (etabliert)\n\nBasierend auf Audit sollten folgende Standards **template-übergreifend** dokumentiert werden:\n\n### Web Component Standards\n\n```typescript\n// ✅ KORREKT\n@Component({ tag: 'kol-xxx', shadow: true })\nexport class KolXxx extends BaseWebComponent<XxxApi> implements WebComponentInterface<XxxApi> {\n private readonly ctrl = new XxxController(this.stateAccess);\n\n @Prop()\n public _prop!: string;\n\n @Watch('_prop')\n public watchProp(value?: string): void {\n this.ctrl.watchProp(value);\n }\n\n @Method()\n @delegateFocus('ref') // Neu Standard\n public async focus(options?: KolFocusOptions): Promise<void> {}\n\n @Event()\n public emitted!: EventEmitter<void>;\n\n @Listen('keydown')\n public handleKeydown(event: KeyboardEvent): void {\n this.ctrl.handleKeydown(event);\n }\n\n public componentWillLoad(): void {\n this.ctrl.componentWillLoad({ prop: this._prop });\n }\n\n public componentDidLoad(): void {\n // Cleanup subscriptions, etc.\n }\n\n public disconnectedCallback(): void {\n this.ctrl.destroy(); // Wichtig für Memory Leak Prevention\n }\n\n public render(): JSX.Element {\n return <Host><XxxFC {...props} /></Host>;\n }\n}\n```\n\n### Controller Standards\n\n```typescript\n// ✅ KORREKT\nexport class XxxController extends BaseController<XxxApi> {\n\tpublic constructor(stateAccess: StateAccess<XxxApi>) {\n\t\tsuper(stateAccess, xxxPropsConfig);\n\t}\n\n\t// Props-Watching\n\tpublic watchProp(value?: string): void {\n\t\tpropConfig.apply(value, (v) => {\n\t\t\tthis.setRenderProp('prop', v);\n\t\t});\n\t}\n\n\t// Event-Emitting\n\tpublic handleClick = (): void => {\n\t\tLog.debug('click'); // Nicht console.log\n\t\t// State mutation\n\t\tthis.setState('state', newValue);\n\t\t// Event-Emitting mit try-catch\n\t\ttry {\n\t\t\tthis.onClickCallback?.();\n\t\t} catch (error) {\n\t\t\tLog.error('Click callback failed', error);\n\t\t}\n\t};\n\n\t// Lifecycle Cleanup\n\tpublic destroy(): void {\n\t\tif (this.intervalId) clearInterval(this.intervalId);\n\t\tif (this.subscription) this.subscription.unsubscribe();\n\t}\n}\n```\n\n### Type Definition Standards\n\n```typescript\n// ✅ KORREKT API Definition\nexport type XxxApi = ApiFromConfig<\n\ttypeof xxxPropsConfig,\n\t{\n\t\tCallbacks: {\n\t\t\tclick: () => void;\n\t\t};\n\t\tEmitters: {\n\t\t\temitted: void; // Vollständig typisiert\n\t\t};\n\t\tListeners: {\n\t\t\tkeydown: KeyboardEvent; // Optional, für Window-Listener\n\t\t};\n\t\tMethods: {\n\t\t\tfocus: (options?: KolFocusOptions) => Promise<void>;\n\t\t};\n\t\tRefs: {\n\t\t\tprimary: HTMLElement;\n\t\t};\n\t\tStates: {\n\t\t\tcount: number;\n\t\t};\n\t}\n>;\n```\n\n### Testing Standards\n\n**Snapshots:**\n\n- Min. 3 Varianten pro Prop\n- Edge cases (empty, very long)\n- State variations (enabled/disabled, show/hide)\n- Format: `executeSnapshotTests<Props>(TAG, [Component], [variants])`\n\n**E2E:**\n\n- Keyboard Interactions (Space, Enter, Escape, Tab)\n- Focus management\n- Event-Listener pattern (addEventListener)\n- Accessibility (ARIA)\n- Format: `test.describe` + `test.skip` mit TODO comments\n\n**JSDoc:**\n\n- Nur auf Stencil-Decorators (`@Prop`, `@Event`, `@Method`, `@State`)\n- Keine JSDoc auf nicht-Stencil Code\n- Focus-Methoden: **immer dokumentieren dass async**\n- Window-Listener: **dokumentieren Stencil auto-cleanup**\n\n---\n\n## 🚨 Build-Blockade: Focus-Type Root-Cause Analyse\n\n**Systemisches Problem (Phase 0):**\n\n```\nKolFocusOptions (kolibri custom)\n └─ type KolFocusOptions = { behavior?: 'auto' | 'smooth' }\n\nvs.\n\nFocusOptions (native browser standard)\n └─ type FocusOptions = { preventScroll?: boolean }\n```\n\n**Wo bricht es:**\n\n- `accordion/shadow.tsx:48` — `HTMLKolButtonWcElement` extends `HTMLElement`\n- Aber `HTMLElement.focus()` expects native `FocusOptions`\n- Aber `KolButton.focus()` returns `Promise<void>` mit `KolFocusOptions`\n- **Type incompatibility** → Build fails\n\n**Langfristige Lösung:**\n\n1. **Option A:** `KolFocusOptions` extends native `FocusOptions`\n\n ```typescript\n export type KolFocusOptions = FocusOptions & {\n \tbehavior?: 'auto' | 'smooth'; // Add custom behaviors\n };\n ```\n\n2. **Option B:** Separate Bridge-Type für Web Components\n\n ```typescript\n // In element-interaction.ts\n export type ComponentFocusOptions = KolFocusOptions; // Ist 'auto' | 'smooth'\n ```\n\n3. **Option C:** Focus-Methods nie native `focus()` überschreiben\n ```typescript\n // Nicht:\n // public focus(options?: FocusOptions): void { }\n // Sondern:\n // public kolFocus(options?: KolFocusOptions): Promise<void> { }\n ```\n\n**Recommendation:** Option A (least breaking)\n\n---\n\n## 📌 Summary & Next Steps\n\n### Aktueller Status\n\n- ✅ Skeleton-Pattern konsistent implementiert\n- ✅ TypeScript-Typen sauber (bis auf FocusOptions)\n- ✅ JSDoc auf Stencil-Decorators vorhanden\n- 🚫 Build-Blockade durch Focus-Type-Mismatch\n- 🚫 Memory-Leak-Risiken nicht dokumentiert\n- 🚫 Testing minimal\n\n### Sofort-Maßnahmen (High Priority)\n\n1. Focus-Type Fix (unblocks Build)\n2. SkeletonController Memory-Leak dokumentieren\n3. Event-Emission Error-Handling\n4. Console → Log-System\n\n### Mittelfristig (Phase 2)\n\n5. JSDoc-Vollständigkeit (State-Felder, Window-Listener)\n6. Test-Expansion (E2E, Snapshots)\n7. onClick Handler Binding fixen\n\n### Langfristig (Code Quality)\n\n8. State-Defaults zentral definieren\n9. Generic Type-Handling refactoren\n10. Documentation: Einheitliche Skeleton-Implementation Guidelines\n\n---\n\n**Report erstellt:** 2026-06-02 \n**Auditor:** Claude Code (team3-Framework) \n**Status:** Bereit zur Umsetzung nach Build-Fix\n",
|
|
570
|
+
"kind": "doc"
|
|
571
|
+
},
|
|
545
572
|
{
|
|
546
573
|
"id": "doc/snapshot-optimierung",
|
|
547
574
|
"group": "docs",
|
|
@@ -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\
|
|
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
|
{
|
|
@@ -1161,7 +1187,7 @@
|
|
|
1161
1187
|
"kol-input-checkbox"
|
|
1162
1188
|
],
|
|
1163
1189
|
"path": "packages/samples/react/src/components/drawer/scrolled.tsx",
|
|
1164
|
-
"code": "// DrawerScrolled Class\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolButton, KolDrawer, KolInputCheckbox } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\nimport { SampleDescription } from '../SampleDescription';\nimport { DrawerRadioAlign } from './partials/align';\n\nexport const DrawerScrolled: FC = () => {\n\tconst drawerElement = useRef<HTMLKolDrawerElement>(null);\n\tconst [align, setAlign] = useState<AlignPropType>('bottom');\n\tconst [useOverflowHandling, setUseOverflowHandling] = useState(true);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample demonstrates how KolDrawer handles content that exceeds the drawer dimensions and shows the correct way to handle overflow. Use the\n\t\t\t\t\t"Enable Overflow Handling" toggle to see the difference between problematic behavior (content exceeding drawer bounds) and the proper solution\n\t\t\t\t\t(overflow handling within the slot content).\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"flex flex-col gap-4 mb-4\">\n\t\t\t\t<DrawerRadioAlign value={align} onChange={(_, value) => setAlign(value as AlignPropType)} />\n\t\t\t\t<KolInputCheckbox\n\t\t\t\t\t_label=\"Enable Overflow Handling (Recommended)\"\n\t\t\t\t\t_checked={useOverflowHandling}\n\t\t\t\t\t_on={{ onChange: (_, value) => setUseOverflowHandling(!!value) }}\n\t\t\t\t/>\n\t\t\t</div>\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t<KolDrawer ref={drawerElement} _label=\"Scrollable Drawer\" _level={2} _align={align}>\n\t\t\t\t\t{useOverflowHandling ? (\n\t\t\t\t\t\t// ✅ Correct approach: Outer container with fixed dimensions and overflow handling\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '90vw' : undefined,\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '90vh' : undefined,\n\t\t\t\t\t\t\t\toverflow: 'auto',\n\t\t\t\t\t\t\t\tpadding: '0',\n\t\t\t\t\t\t\t\tborder: '1px solid #999',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<div\n\t\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : undefined,\n\t\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : undefined,\n\t\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t<p
|
|
1190
|
+
"code": "// DrawerScrolled Class\n\nimport type { AlignPropType } from '@public-ui/components';\nimport { KolButton, KolDrawer, KolInputCheckbox } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useRef, useState } from 'react';\nimport { SampleDescription } from '../SampleDescription';\nimport { DrawerRadioAlign } from './partials/align';\n\nexport const DrawerScrolled: FC = () => {\n\tconst drawerElement = useRef<HTMLKolDrawerElement>(null);\n\tconst [align, setAlign] = useState<AlignPropType>('bottom');\n\tconst [useOverflowHandling, setUseOverflowHandling] = useState(true);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample demonstrates how KolDrawer handles content that exceeds the drawer dimensions and shows the correct way to handle overflow. Use the\n\t\t\t\t\t"Enable Overflow Handling" toggle to see the difference between problematic behavior (content exceeding drawer bounds) and the proper solution\n\t\t\t\t\t(overflow handling within the slot content).\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"flex flex-col gap-4 mb-4\">\n\t\t\t\t<DrawerRadioAlign value={align} onChange={(_, value) => setAlign(value as AlignPropType)} />\n\t\t\t\t<KolInputCheckbox\n\t\t\t\t\t_label=\"Enable Overflow Handling (Recommended)\"\n\t\t\t\t\t_checked={useOverflowHandling}\n\t\t\t\t\t_on={{ onChange: (_, value) => setUseOverflowHandling(!!value) }}\n\t\t\t\t/>\n\t\t\t</div>\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t<KolDrawer ref={drawerElement} _label=\"Scrollable Drawer\" _level={2} _align={align}>\n\t\t\t\t\t{useOverflowHandling ? (\n\t\t\t\t\t\t// ✅ Correct approach: Outer container with fixed dimensions and overflow handling\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '90vw' : undefined,\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '90vh' : undefined,\n\t\t\t\t\t\t\t\toverflow: 'auto',\n\t\t\t\t\t\t\t\tpadding: '0',\n\t\t\t\t\t\t\t\tborder: '1px solid #999',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<div\n\t\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : undefined,\n\t\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : undefined,\n\t\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t\t>\n\t\t\t\t\t\t\t\t<p>✅ Content with proper overflow handling - scrollable within drawer bounds</p>\n\t\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t\t<h3>Large Content Area (Scrollable)</h3>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContainer: {align === 'left' || align === 'right' ? '400px wide' : '90vw wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '90vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tContent: {align === 'left' || align === 'right' ? '150vw wide' : '400px wide'} ×{' '}\n\t\t\t\t\t\t\t\t\t\t{align === 'top' || align === 'bottom' ? '150vh high' : '400px high'}\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Enabled - Container has fixed size with overflow: auto\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t\tWith overflow handling enabled, this content scrolls properly within the drawer container. You can scroll horizontally/vertically to see all\n\t\t\t\t\t\t\t\t\t\tcontent.\n\t\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t) : (\n\t\t\t\t\t\t// ❌ Problematic approach: Content directly exceeds drawer bounds\n\t\t\t\t\t\t<div\n\t\t\t\t\t\t\tstyle={{\n\t\t\t\t\t\t\t\twidth: align === 'left' || align === 'right' ? '150vw' : '400px',\n\t\t\t\t\t\t\t\theight: align === 'top' || align === 'bottom' ? '150vh' : '400px',\n\t\t\t\t\t\t\t\tbackground:\n\t\t\t\t\t\t\t\t\t'linear-gradient(45deg, #f0f0f0 25%, transparent 25%), linear-gradient(-45deg, #f0f0f0 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f0f0f0 75%), linear-gradient(-45deg, transparent 75%, #f0f0f0 75%)',\n\t\t\t\t\t\t\t\tbackgroundSize: '20px 20px',\n\t\t\t\t\t\t\t\tbackgroundPosition: '0 0, 0 10px, 10px -10px, -10px 0px',\n\t\t\t\t\t\t\t\tborder: '2px dashed #ccc',\n\t\t\t\t\t\t\t\tpadding: '20px',\n\t\t\t\t\t\t\t\tdisplay: 'flex',\n\t\t\t\t\t\t\t\tflexDirection: 'column',\n\t\t\t\t\t\t\t\tgap: '20px',\n\t\t\t\t\t\t\t}}\n\t\t\t\t\t\t>\n\t\t\t\t\t\t\t<p>❌ Content exceeding drawer bounds - problematic behavior</p>\n\t\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t\t<h3>Large Content Area</h3>\n\t\t\t\t\t\t\t\t<p>Width: {align === 'left' || align === 'right' ? '150vw (exceeds drawer width)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>Height: {align === 'top' || align === 'bottom' ? '150vh (exceeds drawer height)' : '400px'}</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\t<strong>Overflow Handling:</strong> Disabled - Content extends beyond drawer boundaries\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>\n\t\t\t\t\t\t\t\t\tLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed\n\t\t\t\t\t\t\t\t\tdiam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum\n\t\t\t\t\t\t\t\t\tdolor sit amet.\n\t\t\t\t\t\t\t\t</p>\n\t\t\t\t\t\t\t\t<p>Without overflow handling, this content may extend beyond the drawer boundaries, causing layout issues.</p>\n\t\t\t\t\t\t\t\t<div style={{ marginTop: 'auto', paddingTop: '40px' }}>\n\t\t\t\t\t\t\t\t\t<KolButton _label=\"Close drawer\" _on={{ onClick: () => drawerElement.current?.close() }} />\n\t\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t\t</div>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</KolDrawer>\n\n\t\t\t\t<KolButton _label=\"Open scrollable drawer\" _on={{ onClick: () => drawerElement.current?.open() }} />\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
|
|
1165
1191
|
"kind": "sample"
|
|
1166
1192
|
},
|
|
1167
1193
|
{
|
|
@@ -2692,7 +2718,7 @@
|
|
|
2692
2718
|
"kol-table-stateful"
|
|
2693
2719
|
],
|
|
2694
2720
|
"path": "packages/samples/react/src/components/table/multi-sort.tsx",
|
|
2695
|
-
"code": "import type { FC } from 'react';\nimport React, { useState } from 'react';\n\nimport type { KoliBriTableDataType, KoliBriTableHeaderCellWithLogic, KoliBriTableHeaders } from '@public-ui/components';\nimport { KolButtonLink, KolTableStateful } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst DATE_FORMATTER = Intl.DateTimeFormat('de-DE', {\n\tday: '2-digit',\n\tmonth: '2-digit',\n\tyear: 'numeric',\n});\n\ntype BacklogEntry = {\n\tdate: Date;\n\tassignee: string;\n\tdepartment: string;\n\tpriority: 'High' | 'Medium' | 'Low';\n\tstatus: 'Blocked' | 'In progress' | 'Ready';\n\topenTickets: number;\n};\n\nconst ASSIGNEES = ['Devon Chen', 'Fatima Alvi', 'Leon Köhler', 'Mila Schmidt', 'Sven Lindholm'];\nconst DEPARTMENTS = ['Customer Service', 'Digital Services', 'Infrastructure', 'Municipal Office'];\nconst PRIORITY_SEQUENCE: BacklogEntry['priority'][] = ['High', 'Medium', 'Low'];\nconst STATUS_SEQUENCE: BacklogEntry['status'][] = ['Blocked', 'In progress', 'Ready'];\n\nconst PRIORITY_ORDER = PRIORITY_SEQUENCE.reduce<Record<BacklogEntry['priority'], number>>(\n\t(order, priority, index) => {\n\t\torder[priority] = index;\n\t\treturn order;\n\t},\n\t{} as Record<BacklogEntry['priority'], number>,\n);\n\nconst STATUS_ORDER = STATUS_SEQUENCE.reduce<Record<BacklogEntry['status'], number>>(\n\t(order, status, index) => {\n\t\torder[status] = index;\n\t\treturn order;\n\t},\n\t{} as Record<BacklogEntry['status'], number>,\n);\n\nconst BACKLOG_DATA: BacklogEntry[] = Array.from({ length: 15 }).map((_, index) => ({\n\tdate: new Date(Date.now() - index * 1000 * 60 * 60 * 24),\n\tassignee: ASSIGNEES[index % ASSIGNEES.length],\n\tdepartment: DEPARTMENTS[index % DEPARTMENTS.length],\n\tpriority: PRIORITY_SEQUENCE[index % PRIORITY_SEQUENCE.length],\n\tstatus: STATUS_SEQUENCE[index % STATUS_SEQUENCE.length],\n\topenTickets: (index * 3) % 11,\n}));\n\nconst TABLE_HEADER_CELLS: KoliBriTableHeaderCellWithLogic[] = [\n\t{\n\t\tlabel: 'Assignee',\n\t\tkey: 'assignee',\n\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\t(data0 as BacklogEntry).assignee.localeCompare((data1 as BacklogEntry).assignee, 'de'),\n\t\tsortDirection: 'ASC',\n\t\twidth: 200,\n\t},\n\t{\n\t\tlabel: 'Department',\n\t\tkey: 'department',\n\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\t(data0 as BacklogEntry).department.localeCompare((data1 as BacklogEntry).department, 'de'),\n\t\twidth: 200,\n\t},\n\t{\n\t\tlabel: 'Priority',\n\t\tkey: 'priority',\n\n\t\ttextAlign: 'center',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\tPRIORITY_ORDER[(data0 as BacklogEntry).priority] - PRIORITY_ORDER[(data1 as BacklogEntry).priority],\n\t\tsortDirection: 'DESC',\n\t\twidth: 150,\n\t},\n\t{\n\t\tlabel: 'Status',\n\t\tkey: 'status',\n\n\t\ttextAlign: 'center',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\tSTATUS_ORDER[(data0 as BacklogEntry).status] - STATUS_ORDER[(data1 as BacklogEntry).status],\n\t\twidth: 150,\n\t},\n\t{\n\t\tlabel: 'Open tickets',\n\t\tkey: 'openTickets',\n\n\t\ttextAlign: 'right',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) => (data0 as BacklogEntry).openTickets - (data1 as BacklogEntry).openTickets,\n\t\twidth: 100,\n\t},\n\t{\n\t\tlabel: 'Last updated',\n\t\tkey: 'date',\n\n\t\ttextAlign: 'center',\n\t\trender: (_el, _cell, tuple) => DATE_FORMATTER.format((tuple as BacklogEntry).date),\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) => {\n\t\t\tif ((data0 as BacklogEntry).date < (data1 as BacklogEntry).date) return -1;\n\t\t\telse if ((data1 as BacklogEntry).date < (data0 as BacklogEntry).date) return 1;\n\t\t\telse return 0;\n\t\t},\n\t\twidth: 150,\n\t},\n];\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [TABLE_HEADER_CELLS],\n};\n\nconst HEADERS_VERTICAL: KoliBriTableHeaders = {\n\tvertical: [TABLE_HEADER_CELLS],\n};\n\nexport const MultiSortTable: FC = () => {\n\tconst [verticallHeader, setVerticalHeader] = useState(HEADERS_VERTICAL);\n\tconst [horizontalHeader, setHorizontalHeader] = useState(HEADERS_HORIZONTAL);\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tMulti-sort allows layering multiple column sorts at once. Compare the compact examples with the project backlog showcase to see how the sort order\n\t\t\t\t\tindicator helps track complex prioritisation.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<section className=\"w-full grid gap-6\">\n\t\t\t\t<SampleBlock id=\"vertical\" heading=\"Vertical\">\n\t\t\t\t\t<KolButtonLink _label=\"Reset Table\" _on={{ onClick: () => setVerticalHeader({ vertical: [[...TABLE_HEADER_CELLS]] }) }}></KolButtonLink>\n\t\t\t\t\t<KolTableStateful\n\t\t\t\t\t\t_label=\"Sort Table with Order and Date\"\n\t\t\t\t\t\t_data={BACKLOG_DATA.slice(0, 10)}\n\t\t\t\t\t\t_headers={verticallHeader}\n\t\t\t\t\t\tclassName=\"block\"\n\t\t\t\t\t\t_allowMultiSort={true}\n\t\t\t\t\t/>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"horizontal\" heading=\"Horizontal\">\n\t\t\t\t\t<KolButtonLink _label=\"Reset Table\" _on={{ onClick: () => setHorizontalHeader({ horizontal: [[...TABLE_HEADER_CELLS]] }) }}></KolButtonLink>\n\t\t\t\t\t<KolTableStateful _label=\"Sort Table with Order and Date\" _data={BACKLOG_DATA} _headers={horizontalHeader} className=\"block\" _allowMultiSort={true} />\n\t\t\t\t</SampleBlock>\n\t\t\t</section>\n\t\t</>\n\t);\n};\n",
|
|
2721
|
+
"code": "import type { FC } from 'react';\nimport React, { useState } from 'react';\n\nimport type { KoliBriTableDataType, KoliBriTableHeaderCellWithLogic, KoliBriTableHeaders } from '@public-ui/components';\nimport { KolButtonLink, KolTableStateful } from '@public-ui/react-v19';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nconst DATE_FORMATTER = Intl.DateTimeFormat('de-DE', {\n\tday: '2-digit',\n\tmonth: '2-digit',\n\tyear: 'numeric',\n});\n\ntype BacklogEntry = {\n\tdate: Date;\n\tassignee: string;\n\tdepartment: string;\n\tpriority: 'High' | 'Medium' | 'Low';\n\tstatus: 'Blocked' | 'In progress' | 'Ready';\n\topenTickets: number;\n};\n\nconst ASSIGNEES = ['Devon Chen', 'Fatima Alvi', 'Leon Köhler', 'Mila Schmidt', 'Sven Lindholm'];\nconst DEPARTMENTS = ['Customer Service', 'Digital Services', 'Infrastructure', 'Municipal Office'];\nconst PRIORITY_SEQUENCE: BacklogEntry['priority'][] = ['High', 'Medium', 'Low'];\nconst STATUS_SEQUENCE: BacklogEntry['status'][] = ['Blocked', 'In progress', 'Ready'];\n\nconst PRIORITY_ORDER = PRIORITY_SEQUENCE.reduce<Record<BacklogEntry['priority'], number>>(\n\t(order, priority, index) => {\n\t\torder[priority] = index;\n\t\treturn order;\n\t},\n\t{} as Record<BacklogEntry['priority'], number>,\n);\n\nconst STATUS_ORDER = STATUS_SEQUENCE.reduce<Record<BacklogEntry['status'], number>>(\n\t(order, status, index) => {\n\t\torder[status] = index;\n\t\treturn order;\n\t},\n\t{} as Record<BacklogEntry['status'], number>,\n);\n\nconst BACKLOG_DATA: BacklogEntry[] = Array.from({ length: 15 }).map((_, index) => ({\n\tdate: new Date(Date.now() - index * 1000 * 60 * 60 * 24),\n\tassignee: ASSIGNEES[index % ASSIGNEES.length],\n\tdepartment: DEPARTMENTS[index % DEPARTMENTS.length],\n\tpriority: PRIORITY_SEQUENCE[index % PRIORITY_SEQUENCE.length],\n\tstatus: STATUS_SEQUENCE[index % STATUS_SEQUENCE.length],\n\topenTickets: (index * 3) % 11,\n}));\n\nconst TABLE_HEADER_CELLS: KoliBriTableHeaderCellWithLogic[] = [\n\t{\n\t\tlabel: 'Assignee',\n\t\tkey: 'assignee',\n\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\t(data0 as BacklogEntry).assignee.localeCompare((data1 as BacklogEntry).assignee, 'de'),\n\t\tsortDirection: 'ASC',\n\t\twidth: 200,\n\t},\n\t{\n\t\tlabel: 'Department',\n\t\tkey: 'department',\n\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\t(data0 as BacklogEntry).department.localeCompare((data1 as BacklogEntry).department, 'de'),\n\t\twidth: 200,\n\t},\n\t{\n\t\tlabel: 'Priority',\n\t\tkey: 'priority',\n\n\t\ttextAlign: 'center',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\tPRIORITY_ORDER[(data0 as BacklogEntry).priority] - PRIORITY_ORDER[(data1 as BacklogEntry).priority],\n\t\tsortDirection: 'DESC',\n\t\twidth: 150,\n\t},\n\t{\n\t\tlabel: 'Status',\n\t\tkey: 'status',\n\n\t\ttextAlign: 'center',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) =>\n\t\t\tSTATUS_ORDER[(data0 as BacklogEntry).status] - STATUS_ORDER[(data1 as BacklogEntry).status],\n\t\twidth: 150,\n\t},\n\t{\n\t\tlabel: 'Open tickets',\n\t\tkey: 'openTickets',\n\n\t\ttextAlign: 'right',\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) => (data0 as BacklogEntry).openTickets - (data1 as BacklogEntry).openTickets,\n\t\twidth: 100,\n\t},\n\t{\n\t\tlabel: 'Last updated',\n\t\tkey: 'date',\n\n\t\ttextAlign: 'center',\n\t\trender: (_el, _cell, tuple) => DATE_FORMATTER.format((tuple as BacklogEntry).date),\n\t\tcompareFn: (data0: KoliBriTableDataType, data1: KoliBriTableDataType) => {\n\t\t\tif ((data0 as BacklogEntry).date < (data1 as BacklogEntry).date) return -1;\n\t\t\telse if ((data1 as BacklogEntry).date < (data0 as BacklogEntry).date) return 1;\n\t\t\telse return 0;\n\t\t},\n\t\twidth: 150,\n\t},\n];\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [TABLE_HEADER_CELLS],\n};\n\nconst HEADERS_VERTICAL: KoliBriTableHeaders = {\n\tvertical: [TABLE_HEADER_CELLS],\n};\n\nexport const MultiSortTable: FC = () => {\n\tconst [verticallHeader, setVerticalHeader] = useState(HEADERS_VERTICAL);\n\tconst [horizontalHeader, setHorizontalHeader] = useState(HEADERS_HORIZONTAL);\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tMulti-sort allows layering multiple column sorts at once. Compare the compact examples with the project backlog showcase to see how the sort order\n\t\t\t\t\tindicator helps track complex prioritisation.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<section className=\"w-full grid gap-6\">\n\t\t\t\t<SampleBlock id=\"vertical\" heading=\"Vertical\">\n\t\t\t\t\t<KolButtonLink _label=\"Reset Table\" _on={{ onClick: () => setVerticalHeader({ vertical: [[...TABLE_HEADER_CELLS]] }) }}></KolButtonLink>\n\t\t\t\t\t<KolTableStateful\n\t\t\t\t\t\t_label=\"Sort Table with Order and Date\"\n\t\t\t\t\t\t_data={BACKLOG_DATA.slice(0, 10)}\n\t\t\t\t\t\t_headers={verticallHeader}\n\t\t\t\t\t\tclassName=\"block\"\n\t\t\t\t\t\t_allowMultiSort={true}\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonSortChange: (_e, payload) => console.log('sort changed', payload),\n\t\t\t\t\t\t}}\n\t\t\t\t\t/>\n\t\t\t\t</SampleBlock>\n\t\t\t\t<SampleBlock id=\"horizontal\" heading=\"Horizontal\">\n\t\t\t\t\t<KolButtonLink _label=\"Reset Table\" _on={{ onClick: () => setHorizontalHeader({ horizontal: [[...TABLE_HEADER_CELLS]] }) }}></KolButtonLink>\n\t\t\t\t\t<KolTableStateful _label=\"Sort Table with Order and Date\" _data={BACKLOG_DATA} _headers={horizontalHeader} className=\"block\" _allowMultiSort={true} />\n\t\t\t\t</SampleBlock>\n\t\t\t</section>\n\t\t</>\n\t);\n};\n",
|
|
2696
2722
|
"kind": "sample"
|
|
2697
2723
|
},
|
|
2698
2724
|
{
|
|
@@ -2818,7 +2844,7 @@
|
|
|
2818
2844
|
"kol-table-stateful"
|
|
2819
2845
|
],
|
|
2820
2846
|
"path": "packages/samples/react/src/components/table/stateful-reset-sort.tsx",
|
|
2821
|
-
"code": "import type { FC } from 'react';\nimport React, { useRef } from 'react';\n\nimport type { KoliBriTableDataType, KoliBriTableHeaders } from '@public-ui/components';\nimport { KolButton, KolTableStateful } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\ntype Item = { name: string; score: number };\n\nconst DATA: Item[] = [\n\t{ name: 'Charlie', score: 72 },\n\t{ name: 'Alice', score: 95 },\n\t{ name: 'Bob', score: 88 },\n\t{ name: 'Diana', score: 61 },\n\t{ name: 'Eve', score: 84 },\n];\n\nconst HEADERS: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{\n\t\t\t\tkey: 'name',\n\t\t\t\tlabel: 'Name',\n\t\t\t\tsortDirection: 'ASC',\n\t\t\t\tcompareFn: (a: KoliBriTableDataType, b: KoliBriTableDataType) => (a as Item).name.localeCompare((b as Item).name),\n\t\t\t},\n\t\t\t{\n\t\t\t\tkey: 'score',\n\t\t\t\tlabel: 'Score',\n\t\t\t\ttextAlign: 'right',\n\t\t\t\tcompareFn: (a: KoliBriTableDataType, b: KoliBriTableDataType) => (a as Item).score - (b as Item).score,\n\t\t\t},\n\t\t],\n\t],\n};\n\ntype KolTableStatefulElement = {\n\tresetSort?: () => Promise<void>;\n};\n\nexport const TableStatefulResetSort: FC = () => {\n\tconst tableRef = useRef<HTMLKolTableStatefulElement>(null);\n\n\tconst handleResetSort = () => {\n\t\tconst tableElement = tableRef.current as unknown as KolTableStatefulElement | null;\n\t\tvoid tableElement?.resetSort?.();\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 sample demonstrates the <code>resetSort()</code> method on <code>KolTableStateful</code>. Sort the table manually by clicking on a column header,\n\t\t\t\t\tthen press “Reset Sort” to restore the default sort order defined in <code>_headers</code>.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<section className=\"w-full grid gap-4\">\n\t\t\t\t<KolButton _label=\"Reset Sort\" _on={{ onClick: handleResetSort }} />\n\t\t\t\t<KolTableStateful
|
|
2847
|
+
"code": "import type { FC } from 'react';\nimport React, { useRef } from 'react';\n\nimport type { KoliBriTableDataType, KoliBriTableHeaders } from '@public-ui/components';\nimport { KolButton, KolTableStateful } from '@public-ui/react-v19';\nimport { SampleDescription } from '../SampleDescription';\n\ntype Item = { name: string; score: number };\n\nconst DATA: Item[] = [\n\t{ name: 'Charlie', score: 72 },\n\t{ name: 'Alice', score: 95 },\n\t{ name: 'Bob', score: 88 },\n\t{ name: 'Diana', score: 61 },\n\t{ name: 'Eve', score: 84 },\n];\n\nconst HEADERS: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{\n\t\t\t\tkey: 'name',\n\t\t\t\tlabel: 'Name',\n\t\t\t\tsortDirection: 'ASC',\n\t\t\t\tcompareFn: (a: KoliBriTableDataType, b: KoliBriTableDataType) => (a as Item).name.localeCompare((b as Item).name),\n\t\t\t},\n\t\t\t{\n\t\t\t\tkey: 'score',\n\t\t\t\tlabel: 'Score',\n\t\t\t\ttextAlign: 'right',\n\t\t\t\tcompareFn: (a: KoliBriTableDataType, b: KoliBriTableDataType) => (a as Item).score - (b as Item).score,\n\t\t\t},\n\t\t],\n\t],\n};\n\ntype KolTableStatefulElement = {\n\tresetSort?: () => Promise<void>;\n};\n\nexport const TableStatefulResetSort: FC = () => {\n\tconst tableRef = useRef<HTMLKolTableStatefulElement>(null);\n\n\tconst handleResetSort = () => {\n\t\tconst tableElement = tableRef.current as unknown as KolTableStatefulElement | null;\n\t\tvoid tableElement?.resetSort?.();\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 sample demonstrates the <code>resetSort()</code> method on <code>KolTableStateful</code>. Sort the table manually by clicking on a column header,\n\t\t\t\t\tthen press “Reset Sort” to restore the default sort order defined in <code>_headers</code>.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<section className=\"w-full grid gap-4\">\n\t\t\t\t<KolButton _label=\"Reset Sort\" _on={{ onClick: handleResetSort }} />\n\t\t\t\t<KolTableStateful\n\t\t\t\t\tref={tableRef}\n\t\t\t\t\t_label=\"Table with resettable sort\"\n\t\t\t\t\t_data={DATA}\n\t\t\t\t\t_headers={HEADERS}\n\t\t\t\t\tclassName=\"block\"\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonSortChange: (_e, payload) => console.log('sort changed', payload),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t</section>\n\t\t</>\n\t);\n};\n",
|
|
2822
2848
|
"kind": "sample"
|
|
2823
2849
|
},
|
|
2824
2850
|
{
|
|
@@ -2880,7 +2906,7 @@
|
|
|
2880
2906
|
"kol-table-stateless"
|
|
2881
2907
|
],
|
|
2882
2908
|
"path": "packages/samples/react/src/components/table/stateless-async-paging.tsx",
|
|
2883
|
-
"code": "import type { KoliBriTableHeaders } from '@public-ui/components';\nimport { KolPagination, KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useEffect, useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nimport type { ComplexData } from './test-complex-data';\nimport { COMPLEX_DATA } from './test-complex-data';\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{ label: 'ID', key: 'id', textAlign: 'right', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Common name', key: 'common_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Scientific name', key: 'scientific_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Conservation status', key: 'conservation_status', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Habitat', key: 'habitat', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Diet', key: 'diet', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Geographic range', key: 'geographic_range', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t],\n\t],\n};\n\nexport const TableStatelessAsync: FC = () => {\n\tconst getAsyncData = () => new Promise<{ COMPLEX_DATA: ComplexData[] }>((resolve) => setTimeout(() => resolve({ COMPLEX_DATA }), 5000));\n\tconst loadData = () => {\n\t\tsetLoading(true);\n\t\tgetAsyncData().then((result: Awaited<ReturnType<typeof getAsyncData>>) => {\n\t\t\tsetComplexData(result.COMPLEX_DATA.slice(0, 15));\n\t\t\tsetLoading(false);\n\t\t});\n\t};\n\n\tconst [complexData, setComplexData] = useState<ComplexData[]>([]);\n\tconst [loading, setLoading] = useState<boolean>(true);\n\n\tuseEffect(() => loadData(), []);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample shows how KolTableStateless can be used async and with KolPagination. Paging and sorting are not functional here, because a backend would\n\t\t\t\t\toffer this in real life.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"async\" className=\"w-full relative\">\n\t\t\t\t<KolTableStateless\n\t\t\t\t\t_label=\"Table for demonstration purposes\"\n\t\t\t\t\t_loading={loading}\n\t\t\t\t\t_headers={HEADERS_HORIZONTAL}\n\t\t\t\t\t_data={complexData}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonSort: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t\t<KolPagination\n\t\t\t\t\
|
|
2909
|
+
"code": "import type { KoliBriTableHeaders } from '@public-ui/components';\nimport { KolPagination, KolTableStateless } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useEffect, useState } from 'react';\nimport { SampleBlock } from '../SampleBlock';\nimport { SampleDescription } from '../SampleDescription';\n\nimport type { ComplexData } from './test-complex-data';\nimport { COMPLEX_DATA } from './test-complex-data';\n\nconst HEADERS_HORIZONTAL: KoliBriTableHeaders = {\n\thorizontal: [\n\t\t[\n\t\t\t{ label: 'ID', key: 'id', textAlign: 'right', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Common name', key: 'common_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Scientific name', key: 'scientific_name', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Conservation status', key: 'conservation_status', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Habitat', key: 'habitat', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Diet', key: 'diet', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t\t{ label: 'Geographic range', key: 'geographic_range', textAlign: 'left', width: 160, sortDirection: 'NOS' },\n\t\t],\n\t],\n};\n\nexport const TableStatelessAsync: FC = () => {\n\tconst getAsyncData = () => new Promise<{ COMPLEX_DATA: ComplexData[] }>((resolve) => setTimeout(() => resolve({ COMPLEX_DATA }), 5000));\n\tconst loadData = () => {\n\t\tsetLoading(true);\n\t\tgetAsyncData().then((result: Awaited<ReturnType<typeof getAsyncData>>) => {\n\t\t\tsetComplexData(result.COMPLEX_DATA.slice(0, 15));\n\t\t\tsetLoading(false);\n\t\t});\n\t};\n\n\tconst [complexData, setComplexData] = useState<ComplexData[]>([]);\n\tconst [loading, setLoading] = useState<boolean>(true);\n\n\tuseEffect(() => loadData(), []);\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tThis sample shows how KolTableStateless can be used async and with KolPagination. Paging and sorting are not functional here, because a backend would\n\t\t\t\t\toffer this in real life.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<SampleBlock id=\"async\" className=\"w-full relative\">\n\t\t\t\t<KolTableStateless\n\t\t\t\t\t_label=\"Table for demonstration purposes\"\n\t\t\t\t\t_loading={loading}\n\t\t\t\t\t_headers={HEADERS_HORIZONTAL}\n\t\t\t\t\t_data={complexData}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonSort: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t\t<KolPagination\n\t\t\t\t\t_max={200}\n\t\t\t\t\t_page={1}\n\t\t\t\t\t_siblingCount={0}\n\t\t\t\t\t_boundaryCount={2}\n\t\t\t\t\t_pageSize={15}\n\t\t\t\t\t_on={{\n\t\t\t\t\t\tonChangePage: () => loadData(),\n\t\t\t\t\t}}\n\t\t\t\t/>\n\t\t\t</SampleBlock>\n\t\t</>\n\t);\n};\n",
|
|
2884
2910
|
"kind": "sample"
|
|
2885
2911
|
},
|
|
2886
2912
|
{
|
|
@@ -3441,10 +3467,11 @@
|
|
|
3441
3467
|
"kol-button",
|
|
3442
3468
|
"kol-input-checkbox",
|
|
3443
3469
|
"kol-input-number",
|
|
3444
|
-
"kol-input-text"
|
|
3470
|
+
"kol-input-text",
|
|
3471
|
+
"kol-skeleton"
|
|
3445
3472
|
],
|
|
3446
3473
|
"path": "packages/samples/react/src/scenarios/performance-test.tsx",
|
|
3447
|
-
"code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
|
|
3474
|
+
"code": "import { KolButton, KolInputCheckbox, KolInputNumber, KolInputText, KolSkeleton } from '@public-ui/react-v19';\nimport type { FC } from 'react';\nimport React, { useState } from 'react';\nimport { SampleDescription } from '../components/SampleDescription';\n\ntype ComponentType = 'text' | 'number' | 'checkbox' | 'skeleton';\n\nexport const PerformanceTest: FC = () => {\n\tconst [count, setCount] = useState<number>(100);\n\tconst [activeComponent, setActiveComponent] = useState<ComponentType | null>(null);\n\tconst [renderTime, setRenderTime] = useState<number | null>(null);\n\tconst [isRendering, setIsRendering] = useState<boolean>(false);\n\n\tconst handleEvents = {\n\t\tonInput: (_event: Event, value: unknown) => {\n\t\t\tsetCount(value as number);\n\t\t},\n\t};\n\n\tconst renderComponent = (type: ComponentType, idx: number) => {\n\t\tswitch (type) {\n\t\t\tcase 'text':\n\t\t\t\treturn <KolInputText key={idx} _label={`TextInput #${idx}`} />;\n\t\t\tcase 'number':\n\t\t\t\treturn <KolInputNumber key={idx} _label={`NumberInput #${idx}`} />;\n\t\t\tcase 'checkbox':\n\t\t\t\treturn <KolInputCheckbox key={idx} _label={`Checkbox #${idx}`} />;\n\t\t\tcase 'skeleton':\n\t\t\t\treturn <KolSkeleton key={idx} _name={`skeleton-${idx}`} />;\n\t\t\tdefault:\n\t\t\t\treturn null;\n\t\t}\n\t};\n\n\tconst renderComponents = () => {\n\t\tif (!activeComponent) return null;\n\n\t\tconst components = [];\n\t\tfor (let i = 1; i <= count; i++) {\n\t\t\tcomponents.push(renderComponent(activeComponent, i));\n\t\t}\n\t\treturn components;\n\t};\n\n\tconst handleComponentRender = (type: ComponentType) => {\n\t\tsetIsRendering(true);\n\t\tsetRenderTime(null);\n\t\tconst startTime = performance.now();\n\n\t\tsetActiveComponent(type);\n\n\t\t// Verwende setTimeout um die Renderzeit nach dem nächsten Render-Zyklus zu messen\n\t\tsetTimeout(() => {\n\t\t\tconst endTime = performance.now();\n\t\t\tsetRenderTime(endTime - startTime);\n\t\t\tsetIsRendering(false);\n\t\t}, 0);\n\t};\n\n\tconst handleClear = () => {\n\t\tsetActiveComponent(null);\n\t\tsetRenderTime(null);\n\t\tsetIsRendering(false);\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>This example renders many KoliBri components to show the performance. Choose a component type and set the number of instances to render.</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"w-full mb-6\">\n\t\t\t\t<div className=\"flex flex-wrap items-end gap-4 mb-4\">\n\t\t\t\t\t<KolInputNumber _label=\"Number of components\" _value={count} _min={1} _max={500} _on={handleEvents} />\n\t\t\t\t</div>\n\n\t\t\t\t<div className=\"flex flex-wrap gap-4 mb-6\">\n\t\t\t\t\t<KolButton _label=\"Render TextInputs\" _variant=\"primary\" onClick={() => handleComponentRender('text')} />\n\t\t\t\t\t<KolButton _label=\"Render NumberInputs\" _variant=\"primary\" onClick={() => handleComponentRender('number')} />\n\t\t\t\t\t<KolButton _label=\"Render Checkboxes\" _variant=\"primary\" onClick={() => handleComponentRender('checkbox')} />\n\t\t\t\t\t<KolButton _label=\"Render Skeletons\" _variant=\"primary\" onClick={() => handleComponentRender('skeleton')} />\n\t\t\t\t\t<KolButton _label=\"Clear\" _variant=\"secondary\" onClick={handleClear} />\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{activeComponent && (\n\t\t\t\t<div className=\"w-full mb-4\">\n\t\t\t\t\t<p className=\"text-sm text-gray-600 mb-2\">\n\t\t\t\t\t\tRendering {count} {activeComponent} component{count !== 1 ? 's' : ''}\n\t\t\t\t\t</p>\n\t\t\t\t\t{isRendering && <p className=\"text-sm text-blue-600\">⏱️ Measuring render time...</p>}\n\t\t\t\t\t{renderTime !== null && !isRendering && <p className=\"text-sm text-green-600\">✅ Render time: {renderTime.toFixed(2)}ms</p>}\n\t\t\t\t</div>\n\t\t\t)}\n\n\t\t\t<div className=\"w-full grid gap-4\">{renderComponents()}</div>\n\t\t</>\n\t);\n};\n",
|
|
3448
3475
|
"kind": "scenario"
|
|
3449
3476
|
},
|
|
3450
3477
|
{
|
|
@@ -3536,6 +3563,20 @@
|
|
|
3536
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",
|
|
3537
3564
|
"kind": "scenario"
|
|
3538
3565
|
},
|
|
3566
|
+
{
|
|
3567
|
+
"id": "scenario/scenarios/skeleton",
|
|
3568
|
+
"group": "scenarios",
|
|
3569
|
+
"name": "skeleton",
|
|
3570
|
+
"description": "KolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein \"loaded\" Event mit dem aktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.",
|
|
3571
|
+
"tags": [
|
|
3572
|
+
"kol-button",
|
|
3573
|
+
"kol-input-range",
|
|
3574
|
+
"kol-skeleton"
|
|
3575
|
+
],
|
|
3576
|
+
"path": "packages/samples/react/src/scenarios/skeleton.tsx",
|
|
3577
|
+
"code": "import type { FC } from 'react';\nimport React, { useCallback, useRef, useState } from 'react';\n\nimport { KolButton, KolInputRange, KolSkeleton } from '@public-ui/react-v19';\nimport { SampleDescription } from '../components/SampleDescription';\n\ninterface EventLogEntry {\n\ttimestamp: string;\n\tcount: number;\n\tid: number;\n}\n\nexport const Skeleton: FC = () => {\n\tconst skeletonRef = useRef<HTMLKolSkeletonElement>(null);\n\tconst rangeRef = useRef<HTMLKolInputRangeElement>(null);\n\tconst initialCount = 3;\n\n\tconst durationFormatter = new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'millisecond', maximumFractionDigits: 1 });\n\tconst timeFormatter = new Intl.DateTimeFormat('de-DE', { hour: '2-digit', minute: '2-digit', second: '2-digit' });\n\n\tconst [count, setCount] = useState<number>(initialCount);\n\tconst [eventLog, setEventLog] = useState<EventLogEntry[]>([]);\n\tconst [lastEventTime, setLastEventTime] = useState<string>('');\n\tconst [eventCount, setEventCount] = useState<number>(0);\n\tconst [skeletonCount, setSkeletonCount] = useState<number>(20);\n\n\t// Render benchmark state\n\tconst [generation, setGeneration] = useState<number>(0);\n\tconst [renderDuration, setRenderDuration] = useState<number | null>(null);\n\tconst [isMeasuring, setIsMeasuring] = useState<boolean>(false);\n\n\t// Refs for stable values in closures (no stale closure issues)\n\tconst renderStartTimeRef = useRef<number>(0);\n\tconst expectedCountRef = useRef<number>(20);\n\tconst renderedCountRef = useRef<number>(0);\n\n\tconst handleLoaded = (event: CustomEvent<number>) => {\n\t\tconst now = new Date();\n\t\tconst timestamp = timeFormatter.format(now);\n\t\tconst newEventCount = eventCount + 1;\n\n\t\tsetCount(event.detail);\n\t\tsetLastEventTime(timestamp);\n\t\tsetEventCount(newEventCount);\n\n\t\t// Add to event log (keep only last 5 entries)\n\t\tsetEventLog((prev) => {\n\t\t\tconst newEntry: EventLogEntry = {\n\t\t\t\ttimestamp,\n\t\t\t\tcount: event.detail,\n\t\t\t\tid: newEventCount,\n\t\t\t};\n\t\t\treturn [newEntry, ...prev.slice(0, 4)];\n\t\t});\n\t};\n\n\tconst handleRendered = useCallback(() => {\n\t\trenderedCountRef.current += 1;\n\n\t\tif (renderedCountRef.current >= expectedCountRef.current) {\n\t\t\tconst duration = performance.now() - renderStartTimeRef.current;\n\t\t\tsetRenderDuration(duration);\n\t\t\tsetIsMeasuring(false);\n\t\t}\n\t}, []);\n\n\tconst handleRangeChange = (_event: Event, value: unknown) => {\n\t\tconst newValue = Number(value);\n\t\tsetSkeletonCount(newValue);\n\n\t\t// Start benchmark measurement\n\t\trenderedCountRef.current = 0;\n\t\texpectedCountRef.current = newValue;\n\t\trenderStartTimeRef.current = performance.now();\n\t\tsetRenderDuration(null);\n\t\tsetIsMeasuring(true);\n\t\tsetGeneration((prev) => prev + 1);\n\t};\n\n\tconst handleRangeBlur = () => {\n\t\t// Sicherstellen, dass der interne Wert mit dem State synchronisiert ist\n\t\tif (rangeRef.current) {\n\t\t\trangeRef.current._value = skeletonCount;\n\t\t}\n\t};\n\n\treturn (\n\t\t<>\n\t\t\t<SampleDescription>\n\t\t\t\t<p>\n\t\t\t\t\tKolSkeleton demonstriert Event-Emitter mit automatischem Intervall. Die Komponente emittiert alle 2 Sekunden ein "loaded" Event mit dem\n\t\t\t\t\taktuellen Count-Wert. Über die Buttons kann die Komponente getoggled und fokussiert werden. Der interne ClickButton erhöht bei Klick den Counter.\n\t\t\t\t</p>\n\t\t\t</SampleDescription>\n\n\t\t\t<div className=\"grid md:grid-cols-2 gap-4 mb-4 items-center\">\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4\">\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Toggle Sichtbarkeit\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.toggle(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"primary\"\n\t\t\t\t\t/>\n\t\t\t\t\t<KolButton\n\t\t\t\t\t\t_label=\"Fokus auf Button\"\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonClick: () => skeletonRef.current?.focus(),\n\t\t\t\t\t\t}}\n\t\t\t\t\t\t_variant=\"secondary\"\n\t\t\t\t\t/>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"grid sm:grid-cols-2 gap-4 items-center\">\n\t\t\t\t\t<KolInputRange\n\t\t\t\t\t\tref={rangeRef}\n\t\t\t\t\t\t_label=\"Anzahl der Skeletons\"\n\t\t\t\t\t\t_hideLabel\n\t\t\t\t\t\t_min={1}\n\t\t\t\t\t\t_max={10000}\n\t\t\t\t\t\t_step={25}\n\t\t\t\t\t\t_value={skeletonCount}\n\t\t\t\t\t\t_on={{\n\t\t\t\t\t\t\tonChange: handleRangeChange,\n\t\t\t\t\t\t\tonBlur: handleRangeBlur,\n\t\t\t\t\t\t}}\n\t\t\t\t\t/>\n\t\t\t\t\t<span className=\"text-sm text-gray-600 whitespace-nowrap\">{skeletonCount} Skeletons</span>\n\t\t\t\t</div>\n\t\t\t</div>\n\n\t\t\t{/* Render Benchmark */}\n\t\t\t<div className=\"mb-4 px-3 py-2 border border-gray-300 rounded bg-gray-50 flex items-center gap-4 text-sm\">\n\t\t\t\t<span className=\"font-semibold\">Benchmark:</span>\n\t\t\t\t<span className={isMeasuring ? 'text-orange-600 font-bold' : renderDuration !== null ? 'text-green-600' : 'text-gray-400'}>\n\t\t\t\t\t{isMeasuring ? 'Rendering…' : renderDuration !== null ? 'Fertig' : 'Bereit'}\n\t\t\t\t</span>\n\t\t\t\t<span className=\"font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t{renderDuration !== null ? durationFormatter.format(renderDuration) : '—'}\n\t\t\t\t</span>\n\t\t\t</div>\n\n\t\t\t<div className=\"flex flex-wrap gap-4\">\n\t\t\t\t{Array.from({ length: skeletonCount }, (_, idx) => (\n\t\t\t\t\t<KolSkeleton\n\t\t\t\t\t\tkey={`skeleton-${generation}-${idx}`}\n\t\t\t\t\t\t_name={`Example ${idx}`}\n\t\t\t\t\t\tonLoaded={idx === 0 ? handleLoaded : undefined}\n\t\t\t\t\t\tonRendered={handleRendered}\n\t\t\t\t\t\tref={idx === 0 ? skeletonRef : undefined}\n\t\t\t\t\t/>\n\t\t\t\t))}\n\t\t\t</div>\n\n\t\t\t<div className=\"mt-6 p-4 border border-gray-300 rounded-lg bg-gray-50\">\n\t\t\t\t<h3 className=\"text-lg font-semibold mb-3\">Event Monitor</h3>\n\t\t\t\t<div className=\"grid grid-cols-1 md:grid-cols-2 gap-4\">\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Aktueller Count-Wert:</p>\n\t\t\t\t\t\t<p className=\"text-2xl font-bold text-blue-600\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{count}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t\t<div>\n\t\t\t\t\t\t<p className=\"font-medium\">Letztes Event:</p>\n\t\t\t\t\t\t<p className=\"text-lg\" aria-live=\"polite\">\n\t\t\t\t\t\t\t{lastEventTime || 'Noch kein Event empfangen'}\n\t\t\t\t\t\t</p>\n\t\t\t\t\t</div>\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4\">\n\t\t\t\t\t<p className=\"font-medium mb-2\">\n\t\t\t\t\t\tEvents empfangen: <span className=\"font-bold\">{eventCount}</span>\n\t\t\t\t\t</p>\n\t\t\t\t\t{eventLog.length > 0 && (\n\t\t\t\t\t\t<div>\n\t\t\t\t\t\t\t<p className=\"font-medium mb-2\">Event-Historie (letzte 5):</p>\n\t\t\t\t\t\t\t<ul className=\"text-sm space-y-1 max-h-32 overflow-y-auto\">\n\t\t\t\t\t\t\t\t{eventLog.map((entry) => (\n\t\t\t\t\t\t\t\t\t<li key={entry.id} className=\"flex justify-between items-center p-2 bg-white rounded border\">\n\t\t\t\t\t\t\t\t\t\t<span>\n\t\t\t\t\t\t\t\t\t\t\t#{entry.id}: Count = {entry.count}\n\t\t\t\t\t\t\t\t\t\t</span>\n\t\t\t\t\t\t\t\t\t\t<span className=\"text-gray-500\">{entry.timestamp}</span>\n\t\t\t\t\t\t\t\t\t</li>\n\t\t\t\t\t\t\t\t))}\n\t\t\t\t\t\t\t</ul>\n\t\t\t\t\t\t</div>\n\t\t\t\t\t)}\n\t\t\t\t</div>\n\t\t\t\t<div className=\"mt-4 p-3 bg-blue-50 rounded\">\n\t\t\t\t\t<p className=\"text-sm text-blue-800\">\n\t\t\t\t\t\t💡 <strong>Tipp:</strong> Die Komponente emittiert automatisch alle 2 Sekunden ein Event. Klicke auf den "Click Button" in der Komponente,\n\t\t\t\t\t\tum den Count-Wert zu erhöhen.\n\t\t\t\t\t</p>\n\t\t\t\t</div>\n\t\t\t</div>\n\t\t</>\n\t);\n};\n",
|
|
3578
|
+
"kind": "scenario"
|
|
3579
|
+
},
|
|
3539
3580
|
{
|
|
3540
3581
|
"id": "scenario/scenarios/static-form",
|
|
3541
3582
|
"group": "scenarios",
|
|
@@ -3634,9 +3675,9 @@
|
|
|
3634
3675
|
"id": "spec/ARC42-SKELETON",
|
|
3635
3676
|
"group": "spec",
|
|
3636
3677
|
"name": "ARC42-SKELETON",
|
|
3637
|
-
"description": "The 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.",
|
|
3638
3679
|
"path": "packages/tools/mcp/node_modules/@public-ui/components/docs/ARC42-SKELETON.md",
|
|
3639
|
-
"code": "# Skeleton Blueprint Architecture (arc42)\n\n## 1. Introduction and Goals\n\nThe skeleton architecture describes how KoliBri web components are built in a highly maintainable and decoupled fashion. It is the binding reference structure for new components.\n\nThe architecture is organized into **two layers** plus an optional reusable unit of logic:\n\n- **Web Component (WC)** — the orchestrator. It owns the Stencil lifecycle (`@Prop`/`@State`/`@Watch`/`@Method`), normalizes incoming props, manages reactive state, composes optional Behaviors, and feeds fully resolved render props to the Functional Component.\n- **[Behaviors](../src/internal/functional-components/base-behavior.ts)** — optional, composable logic modules (e.g. `TooltipBehavior`). A WC may compose zero or more Behaviors. They manage their own render props but receive state access from their host WC.\n- **Functional Component (FC)** — a pure, stateless renderer. It renders solely from the props handed to it and never mutates state.\n- **[Schema helpers](../src/internal/props/)** — house prop types, normalization and validation helpers shared across layers.\n\nPrimary goals:\n\n- illustrate a minimal separation of concerns for long-term maintainability\n- keep the WC as the single orchestrator — no indirection layer between the custom element and the renderer\n- factor out only genuinely reusable cross-component logic into Behaviors\n- enforce consistent validation and type-safety boundaries\n- keep per-prop special treatment to a minimum — validation, defaults and hints are uniform across every component using a prop; deviations are documented exceptions with a reason, not per-component one-offs\n- document an end-to-end implementation pipeline that teams can replicate when bootstrapping new components\n\n### Blueprint Layout\n\nThe skeleton mirrors the structure recommended for production-ready components. Every web component definition lives in its own folder under `src/components/`, while reusable internals (functional components, behaviors, prop schemas) reside in the shared `src/internal/` directory. Each folder holds a single responsibility to make the pipeline explicit:\n\n```text\nsrc/\n├── components/\n│ └── <component>/ # Web component folder — one folder per component\n│ ├── component.tsx # Orchestrator: props, watchers, lifecycle, render\n│ ├── snapshot.spec.tsx # Snapshot test (Jest) — co-located\n│ └── <component>.e2e.ts # Interaction test (Playwright)\n└── internal/ # Shared internals\n ├── functional-components/\n │ ├── <component>/ # Component-specific logic\n │ │ ├── api.tsx # Type definitions + props config\n │ │ └── component.tsx # Stateless functional component\n │ ├── tooltip/ # Tooltip behavior + FC\n │ │ ├── api.tsx\n │ │ ├── behavior.ts # TooltipBehavior\n │ │ └── component.tsx\n │ ├── bem-root-node/ # Single-root BEM wrapper FC\n │ │ └── component.tsx\n │ ├── base-behavior.ts # Shared behavior base class\n │ ├── base-web-component.ts # Shared WC base class (orchestrator helpers)\n │ └── generic-types.ts # Interface contracts\n └── props/ # Prop types, normalisation and validation\n ├── helpers/\n │ ├── factory.ts # Prop, SimpleProp, PropDefinition, apply()\n │ └── normalizers.ts # normalizeString, normalizeInteger, etc.\n ├── label.ts # LabelProp\n ├── name.ts # NameProp\n ├── show.ts # ShowProp\n └── index.ts # Re-exports\n```\n\nThis modular layout is the backbone for the architectural patterns described in the following chapters.\n\n## 2. Architecture Constraints\n\n- **Stencil** is used for authoring web components with **shadow: true** only (Shadow DOM enabled for style isolation).\n- A component that embeds another component inside its own shadow DOM renders that component's **Functional Component** through an item (see §4 Embedded Components). The only element without Shadow DOM is `kol-tooltip-wc`; it stays deprecated and is kept only for DESYBRI.\n- Components must compile to framework-agnostic Custom Elements.\n- Public API properties use an underscored naming convention (e.g. `_name`) to separate external inputs from internal state.\n- Documentation and code follow the `KoliBri` casing and repository conventions.\n\n## 3. Context and Scope\n\nThe skeleton lives inside `packages/components` and does not depend on runtime frameworks. External consumers interact through HTML attributes or DOM APIs.\n\n**Shadow DOM Strategy**: KoliBri uses Web Components with Shadow DOM enabled (`shadow: true`) by default. This ensures:\n\n- **Style Isolation**: Component styles cannot leak into host page styles and vice versa\n- **Encapsulation**: Components maintain consistent appearance regardless of host environment\n- **Maintainability**: Clear boundaries prevent unintended style interactions\n\n```mermaid\nflowchart LR\n Consumer[External Consumer] --> WC[Web Component]\n WC -.-> Schema[Schema Helpers]\n WC --> Behavior[Behavior, optional]\n WC --> FC[Functional Component]\n FC --> WC\n WC --> Consumer\n```\n\nThe external consumer interacts solely with the custom element. The WC is the orchestrator: it normalizes\nincoming values (consulting the schema helpers), composes optional Behaviors, and hands the resulting render\nprops to the stateless functional component. The resulting DOM is patched back into the WC and finally\nexposed to the consumer. Each arrow corresponds to an explicit TypeScript contract, ensuring that\nintegration points are discoverable and type safe.\n\n## 4. Solution Strategy\n\nThe blueprint enforces unidirectional data flow. The WC owns the full lifecycle: it normalizes props, manages reactive state, composes Behaviors, and renders. There is no controller/aspect class between the custom element and the FC.\n\n### Web Component Layer\n\nThe WC **is** the orchestrator. It extends `BaseWebComponent<Api>`, which provides:\n\n- `propsConfig` — the concrete component declares its props config as this field. The base seeds the render-prop store with its defaults on the first access, so even a `@Watch` fired by a prop assignment before `componentWillLoad` finds the defaults (#11449).\n- `setRenderProp(key, value)` / `getRenderProp(key)` — store and read normalized render props.\n- `setRawProp(key, value)` / `getRawProp(key)` — store/read the last raw (unprocessed) `@Prop` value, useful for change detection in watchers.\n- `stateAccess` — a `{ setState, getState }` bundle passed to composed Behaviors.\n- `stateLess` — a frozen sentinel for Behaviors that use no `@State`.\n\nResponsibilities of the WC:\n\n- Declares the public API using underscored props (e.g. `_name`).\n- Owns the Stencil-specific decorators (`@Prop`, `@Event`, `@Watch`, `@State`, `@Listen`). Watchers normalize incoming values via schema helpers and store them with `setRenderProp`.\n- Manages derived/UI state on `@State` fields, updated through `setState`/`getState` for reactivity.\n- Composes optional Behaviors (e.g. `private readonly tooltipBehavior = new TooltipBehavior(this.stateAccess)`).\n- Renders the FC inside a bare `<Host>` (shadow DOM). No `<Host class=\"kol-…\">` — the tag name plus Shadow DOM are sufficient.\n\nA WC has **exactly one orchestrator (itself)** plus zero or more Behaviors. A WC may compose Behaviors, never other WCs.\n\nWhen several custom elements are tag variants of **one** FC (`kol-button`, `kol-button-link` and `kol-split-button` all render `ButtonFC`; `kol-link` and `kol-link-button` all render `LinkFC`), the orchestrator implementation is shared through an abstract base class next to the element (`components/button/base.tsx` → `BaseButtonWebComponent`, `components/link/base.tsx` → `BaseLinkWebComponent`). The base extends `BaseWebComponent<Api>`, carries no Stencil decorator and holds the composed Behaviors, the event handlers, one `apply<Prop>()` method per prop and the FC render call. The concrete element keeps everything Stencil has to see in the component class: `@Component`, `@Element`, `@State`, `@Method`, every `@Prop` with a one-line `@Watch` that calls the matching `apply<Prop>()`, and the lifecycle methods, which delegate to the base (see design decision 16).\n\n```tsx\n// WC — the orchestrator (KolLink, reference implementation)\nexport class KolLink extends BaseWebComponent<LinkApi> implements WebComponentInterface<LinkApi> {\n\tprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n\tprotected readonly propsConfig: PropsConfigShape = linkPropsConfig;\n\n\t@Prop() public _href!: string;\n\n\t@Watch('_href')\n\tpublic watchHref(value?: string): void {\n\t\threfProp.apply(value, (v) => this.setRenderProp('href', v));\n\t}\n\n\tpublic componentWillLoad(): void {\n\t\threfProp.apply(this._href, (v) => this.setRenderProp('href', v));\n\t\tlabelWithExpertSlotProp.apply(this._label, (v) => this.setRenderProp('label', v));\n\t\t// …all other props…\n\t\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n\t}\n\n\tpublic render(): JSX.Element {\n\t\treturn (\n\t\t\t<Host>\n\t\t\t\t<LinkFC\n\t\t\t\t\thref={this.getRenderProp('href')}\n\t\t\t\t\tlabel={this.getRenderProp('label')}\n\t\t\t\t\trefTooltip={this.tooltipBehavior.setTooltipElementRef}\n\t\t\t\t\t// …all other render props…\n\t\t\t\t/>\n\t\t\t</Host>\n\t\t);\n\t}\n}\n```\n\n#### Member order\n\nEvery Stencil component class lists its members in the same order:\n\n1. `static` members\n2. `@Element`\n3. each `@State`, directly followed by its `@Watch` method(s) if it has any\n4. other fields (refs, behaviors, translations, items)\n5. `constructor`\n6. each `@Prop`, directly followed by its `@Watch` method(s); a watcher of several props follows the first of them\n7. `@Event`\n8. `@Method`\n9. lifecycle methods, grouped by phase (load, update, render, disconnect): `connectedCallback`, `componentWillLoad`, `componentDidLoad`, `componentShouldUpdate`, `componentWillUpdate`, `componentDidUpdate`, `componentWillRender`, `componentDidRender`, `disconnectedCallback`. This is a declaration convention, not the order in which Stencil runs the hooks (`componentWillRender` and `componentDidRender` run before `componentDidLoad`)\n10. `@Listen`\n11. helpers and handlers: the other methods, accessors and arrow-function fields, whatever their visibility\n12. `render`\n\nProperty initializers run in declaration order. A property whose value another initializer reads therefore stays before that property, even when its group comes later (e.g. `translateFilenameText` before the `@State` `filename` of `kol-input-file`). `component-structure.spec.ts` pins the member order of all components. For every class under `src` it also checks that no initializer reads an own property declared after it, directly (`this.x`), through own getters it reads (`this.derived`) or through own methods and arrow-function properties it calls (`this.compute()`), also nested through the called bodies. Every other path is not traced, e.g. a callee that receives `this` (`new Behavior(this)`), a synchronously run callback (an IIFE, `[1].map(() => this.later)`), `call`/`apply`/`bind` and element access (`this['x']`); keep such reads behind the property they read.\n\n### Public API Contract (Migration Parity)\n\nThe public API of a web component is exactly its set of `@Prop`/`@Method` members — for KoliBri\nthe underscored props (`_href`, `_label`, …) plus the public methods (`focus()`, `click()`, …) —\n**including** their JSDoc comments, their types, their defaults and any `@deprecated` markers.\n\n**Migration rule: the public API of a migrated component must be identical to its predecessor.**\nWhen refactoring a legacy component to the skeleton architecture, the migrated WC must expose the\nsame public members, with the same types (schema aliases, not downgraded primitives), the same\ndefaults and the same documentation. It must not add, remove, rename, retype or undocumented any\npublic member. A behavioural difference behind an unchanged member is a separate, consciously\nreviewed decision — never a side effect of the migration.\n\n**The FC's props are internal, not public API.** The functional component is an internal renderer\ncontract: it may offer more (or differently typed) props than the WC exposes. The WC is the API\ngate — it decides which render props are fed from public props and which stay at their internal\ndefaults. Never derive the public API from the FC's props, and never add a public `@Prop` \"because\nthe FC has one\". Conversely, internal-only capabilities (e.g. `ariaOwns`, `customClass`, `tabIndex`\non `LinkFC`) may stay unreachable from the outside when the predecessor component did not expose\nthem either.\n\n**Why the JSDoc is part of the contract:** `stencil build --docs` generates `docs-vscode`,\n`docs-readme` and — via `generateCustomElementsJson` — the `custom-elements.json` descriptors\ndirectly from `prop.docs` / `method.docs`. A `@Prop` without a JSDoc comment silently loses\nIntelliSense and generated documentation for every adapter package. The same applies to\n`@deprecated` markers, which announce planned removals to consumers.\n\n**Compile-time enforcement:** the WC implements the schema interface from `src/schema` (e.g.\n`implements LinkProps`) **in addition to** `WebComponentInterface<Api>`. The generic\n`WebComponentInterface` alone derives its prop types from the internal prop definitions\n(primitives like `string`/`boolean`), which would allow the public types to silently drift away\nfrom the schema. The schema alias types (`HrefPropType`, `LabelWithExpertSlotPropType`,\n`AlternativeButtonLinkRolePropType`, …) are structurally identical to the internal external types,\nso both `implements` clauses can coexist. Legacy state-shape requirements of `*API` types (e.g.\n`InternalLinkAPI`'s `state` member) are replaced by the render-prop store; implement the `*Props`\ninterface instead.\n\n**Verification (mandatory before merging a migration):** extract every `@Prop`/`@Method`\ndeclaration with its preceding JSDoc block from the predecessor file (`git show <base>:<path>`)\nand from the migrated file, and diff the two member lists. Any difference is a finding that needs\nan explicit justification in the PR description.\n\nThis is enforced continuously by the contract tests in\n[`src/components/public-api/`](../src/components/public-api/contract.ts): one `<component>.spec.ts` per component folder\nextracts the `@Prop`/`@Method` members (including JSDoc, types, defaults and requiredness) from the\ncomponent sources and compares them against a pinned contract, using the helpers in `contract.ts`.\n**Pin every component before its migration** (against the legacy `shadow.tsx`) and point the pin to\n`component.tsx` in the migration PR — the pin makes any public API change fail the build, which is\nexactly the point: such a change is a breaking change and must be an explicit, reviewable edit. One\nfile per component keeps parallel migrations free of merge conflicts.\n\n### Theming Contract (Shadow DOM Structure and BEM Classes)\n\nBesides the public API, a component exposes its rendered structure to themes: the nodes of its\nshadow DOM and the BEM classes on them, including a class on the host element. Themes, our own and\nthose of consumers, select these classes. This theming contract is versioned differently from the\npublic API:\n\n| Change | Classification | Release |\n| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------------- |\n| `@Prop`/`@Method`/`@Event`/slot, their types, defaults, documentation and behaviour, exported types | breaking change | major |\n| internal DOM structure (added, removed or moved nodes) and the BEM classes the structure needs (renamed, added, removed or moved classes) | **theming breaking change** | at least minor |\n\nA theming breaking change is not treated as a hard breaking change, because a theme can be adapted\nto it largely automatically: the theme's own visual snapshots show every affected selector, and the\n[`zero-visual-delta-handoff`](../../../../../.claude/skills/zero-visual-delta-handoff/SKILL.md) skill\ntogether with `pnpm check:skeleton-selectors` drives the theme back to zero pixel differences.\n\nRules for such a change:\n\n- The pull request adapts every theme of this repository in the same change, with zero pixel\n differences in the visual review.\n- It carries the release label `release:theming`, so the change appears in the changelog under\n _Theming_, and its title or description marks it as a **theming breaking change**.\n- The description lists each affected class or node with its old and new form, so theme authors\n can adapt their selectors.\n\n### Behavior Layer\n\nA Behavior is a reusable unit of logic that lives **inside** a WC. It extends `BaseBehavior<Api>` and:\n\n- Manages its own render props (`setRenderProp`/`getRenderProp`), seeded from its own props config in the `BaseBehavior` constructor.\n- Receives `StateAccess<Api>` from its host WC — either a real bundle or `BaseWebComponent.stateLess` when it manages no `@State`.\n- Exposes watcher entry points and lifecycle hooks (`componentWillLoad`) that the WC delegates to.\n- Must never instantiate other Behaviors directly — only the WC composes them.\n\nRule of thumb: a Behavior exists only when the same logic is genuinely shared across multiple components. The sole current example is `TooltipBehavior`, composed by link, button, and similar components.\n\n```tsx\n// Inside a WC\nprivate readonly tooltipBehavior = new TooltipBehavior(this.stateAccess);\n\n// delegating to the behavior from a watcher\nprivate applyTooltipAlign(value?: string): void {\n\ttooltipAlignProp.apply(value, (v) => {\n\t\tthis.setRenderProp('tooltipAlign', v);\n\t\tthis.tooltipBehavior.watchAlign(v);\n\t});\n}\n```\n\nFor a Behavior that has no `@State` fields, pass `BaseWebComponent.stateLess`:\n\n```tsx\nprivate readonly someStatelessBehavior = new SomeBehavior(BaseWebComponent.stateLess);\n```\n\n### Functional Component Layer\n\nThe FC is a pure renderer. It:\n\n- Receives normalized render props, callbacks, emitters and refs from the WC.\n- Avoids any side effects or state mutation. User interactions are signalled via DOM events/callbacks back to the WC.\n- Maps props to accessible markup and wires refs for imperative access when required.\n- May call stateless utility functions (e.g. `translate()`, formatters) directly — the `Callbacks` bucket in `ComponentApi` is reserved for event-driven callbacks only, not data accessors.\n\n#### BemRootNodeFC Pattern\n\nFCs use `BemRootNodeFC` to produce a single-root BEM structure. It renders exactly one `<div>` root node (enforcing a single-root FC), accepts a typed `block` name and `modifiers`, and merges an optional forwarded `class`:\n\n```tsx\nexport const LinkFC: FC<FunctionalComponentProps<LinkApi>> = (props) => {\n\tconst { disabled, inline, hideLabel, customClass, variant } = props;\n\t// …\n\treturn (\n\t\t<BemRootNodeFC\n\t\t\tblock=\"kol-link\"\n\t\t\tclass={clsx({ [customClass]: variant.includes('custom'), [classNameFromVariant(variant, 'link')]: variant.length > 0 })}\n\t\t\tmodifiers={{\n\t\t\t\tdisabled: disabled === true,\n\t\t\t\t'hide-label': hideLabel === true,\n\t\t\t\tinline: inline === true,\n\t\t\t\tstandalone: inline === false,\n\t\t\t}}\n\t\t>\n\t\t\t<a class=\"kol-link__interactive-element\" /* … */>…</a>\n\t\t</BemRootNodeFC>\n\t);\n};\n```\n\nThe `block` and `modifiers` keys are validated against `KoliBriComponentsBemSchema`, so `block=\"kol-link\"` is type-checked and `modifiers={{ disabled: true }}` only accepts registered modifier keys. The output is `<div class=\"kol-link kol-link--disabled …\">`; inner elements use plain BEM element classes (`kol-link__interactive-element`, `kol-link__text`).\n\n**Registration requirement:** before using `BemRootNodeFC block=\"kol-xxx\"`, the block must be registered in `src/schema/bem-registry.ts` in **both** places — the exported `KoliBriComponentsBemSchema` type (required for compilation) and the runtime `BEM` const (consumed by the `kolibri-cli` SCSS generator). Type-only registration compiles and renders, but silently breaks theme SCSS generation.\n\n**When not to use it:** `BemRootNodeFC` always renders a `<div>` root. For FCs whose semantic root is another element (e.g. `ClickButtonFC` renders a `<button>`), build the root manually with `bem.forBlock('kol-xxx')(modifiers)` instead — the same typed schema applies. `LinkFC` and `ButtonFC` use `BemRootNodeFC` (both have extra siblings — tooltip, description — alongside their interactive element, so the wrapper is required, not just one non-div root); `SkeletonFC` and `ClickButtonFC` use direct `bem.forBlock` calls because their FC root _is_ the single non-div interactive element.\n\n### Embedded Components (Items)\n\nWhen a component renders another component inside its own shadow DOM — the close button of an alert, the sort buttons of a table, the page size select of a pagination — it renders that component's FC directly, so its own stylesheet and the theme reach the inner `.kol-…` classes. The orchestration the embedded element would own (resolved props with the element's `@Prop` defaults, Behaviors such as the tooltip, refs, event handlers) lives in an **item**: a plain object with closures, created once per embedded instance and owned by the embedding WC.\n\n| Item | Renders |\n| ---------------------------------------------------- | -------------------------------- |\n| `createButtonItem` (`button/item.ts`) | `ButtonFC` |\n| `createLinkItem` (`link/item.ts`) | `LinkFC` |\n| `createPopoverButtonItem` (`popover-button/item.ts`) | `PopoverButtonFC` |\n| `createDialogItem` (`dialog/item.tsx`) | `DialogFC` with a card |\n| `PageSizeSelect` (`pagination/page-size-select.tsx`) | the select field of `kol-select` |\n\n- `getFcProps(…)` returns the fully resolved FC props; call it once per render.\n- `syncListeners()` runs from `componentDidRender`, `destroy()` from `disconnectedCallback`.\n- A variable number of embedded instances (one action button per table row) goes through `createItemPool` (`item-pool.ts`): each render pass takes its items by key, and `endRender()` syncs them and destroys the ones the pass no longer used.\n- The KoliBri DOM events of the embedded component are dispatched on its FC root, where the embedded element used to be, so they bubble the same way.\n\n### Schema Helper Layer\n\nWeb components receive dynamic values from HTML attributes, but internal rendering requires statically typed data. The schema helper layer bridges that gap through **graceful degradation**: attempt minimal type conversion, then validate, but never force invalid data into types.\n\nDesign principles:\n\n- **Fail gracefully**: Invalid data is ignored rather than causing errors\n- **Minimal conversion**: Only obvious transformations (string numbers → numbers)\n- **Type guarantees**: Once validated, types are guaranteed throughout the component lifecycle\n- **Single source of truth for defaults**: Default values are defined explicitly in shared prop/schema helpers and consumed by components, avoiding duplicated or drifting defaults\n- **One definition per prop**: A public prop name has one definition in `internal/props` (e.g. `disabledProp` for every `_disabled`), reused by all components. A second definition for the same render key exists only where the props of different components differ functionally (other value type, value set or documented default), where a shared factory types the value per component (callbacks, links, options), or where the meaning of the prop differs (`labelWithExpertSlotProp` beside `labelProp`: its empty string enables the expert slot); `prop-keys.spec.ts` lists these variants with their reason. Definitions that share behavior share the implementation: under different keys `createAlignPropDefinition` (`_align`, `_popoverAlign`, `_tooltipAlign`), under one key the typed factories `createCallbacksPropDefinition`, `createLinksPropDefinition` and `createOptionsPropDefinition`\n- **One explicit schema type per prop**: every prop value type is the named schema type from `src/schema/props`; as a rule, one readable PropType per functionality is shared by all of its property definitions, and prop bags, prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining a native type (see _Explicit Schema Types per Prop_)\n- **As few special treatments per prop as possible**: a prop's validation, default and hints are the same for every component using it; a component-specific deviation is a documented exception with a reason (e.g. the `LabelWithExpertSlotPropType` empty-string sentinel), never a silent one-off (see §1 Primary Goals)\n\n#### Dual-Type Props\n\nEach prop can define an **external** (Web Component API) and an **internal** (FC) type. The external type may be more permissive to support shorthand values from HTML attributes, while the internal type is always the normalized form.\n\n`Prop<K, TExternal, TInternal>` encodes both via phantom keys (`__input_${K}` carries the external type, `__propInternal__` carries the internal type). `SimpleProp<K, T>` is a shorthand when both types are identical:\n\n```typescript\n// Different external and internal types:\ntype ColorProp = Prop<'color', ColorPair | string, ColorPair>;\n// └─ Key └─ Web Component └─ FC\n\n// Same external and internal type (shorthand):\ntype NameProp = SimpleProp<'name', NamePropType>;\n// └─ Key └─ Both types\n```\n\n#### Explicit Schema Types per Prop\n\nEvery prop has exactly one named **schema type** in `src/schema/props` (e.g. `DisabledPropType` in\n`schema/props/disabled.ts`). A schema type may be structurally as simple as a native type — naming it\nis the point, not making it complex. The name is the single spelling of the type: the prop bag, the\nprop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all\nreference it, and no layer inlines a native type instead:\n\n```typescript\n// schema/props/disabled.ts — the named schema type (its structure does not change)\nexport type DisabledPropType = boolean;\n\n// internal/props/disabled.ts — the definition references the schema type\nexport type DisabledProp = SimpleProp<'disabled', DisabledPropType>;\nexport const disabledProp = createPropDefinition<DisabledProp>('disabled', false, normalizeBoolean);\n\n// components/button/component.tsx — @Prop, watcher and apply carry the schema type\n@Prop() public _disabled?: DisabledPropType = false;\n\n@Watch('_disabled')\npublic watchDisabled(value?: DisabledPropType): void {\n\tdisabledProp.apply(value, (v) => this.setRenderProp('disabled', v));\n}\n```\n\nOne caveat lives in the test toolchain, not in the compiled output: the pinned Stencil transpile does\nnot coerce attribute strings for imported type aliases\n([stenciljs/core#4663](https://github.com/stenciljs/core/issues/4663), fixed upstream), so jest sees\nthe raw attribute string on an aliased boolean/number prop while the compiled dist metadata resolves\nthe alias and the real runtime is unaffected. Tests therefore assert the normalized render props\ninstead of raw `@Prop` values; the next Stencil upgrade removes the caveat entirely.\n\nWithout the shared name, every layer spells the type its own way (`SimpleProp<'disabled', boolean>`,\n`watchDisabled(value?: boolean)`) and nothing ties the spellings together. With it, `apply`, watcher\nand FC signatures carry the domain term, drift between the layers fails the compiler instead of\nsurfacing in review, and an evolution of the schema type moves every layer at once.\n\nAs a rule, one readable PropType is defined per functionality and shared by all of its property\ndefinitions — whether there is one (`disabledProp` for `_disabled`) or several (`inputDateMaxProp`,\n`inputMaxProp`, `maxProp` and `paginationMaxProp` for `_max`, each with its own normalizer,\nvalidator or default). The shared type — not only the prop key string — is what connects the\ndefinitions of a functionality. Only in individual cases, where the meaning of the value itself\ndiffers, is a special readable PropType variant introduced — e.g. `LabelWithExpertSlotPropType`\nbeside `LabelPropType`, or the distinct `_value` types of the checkbox, radio, select, date and\nnumber inputs. `prop-keys.spec.ts` documents the variants per render key.\n\nNaming roles stay distinct: `XxxPropType` is the schema value type, `PropXxx` the schema prop bag\nand `XxxProp` the prop definition in `internal/props`.\n\nWhich variant a component uses follows its rendered markup: a `_label` that flows into the `span`\nexpert slot (`<slot name=\"expert\">`) is `LabelWithExpertSlotPropType` — the interactive elements,\nthe form-field labels and the heading (its label sits in the heading tag next to the expert slot).\nA `_label` that is a landmark name, a caption or a pure `aria-label` without an expert slot stays\n`LabelPropType` — even when the component renders unrelated expert slots elsewhere (e.g. for the\nquote content or the tree item button). The decisive test is who switches the slot: a label is a\nsentinel carrier (`''` enables the slot) only where the label value itself toggles it. A label\nrendered through a slot the component keeps open on its own — the tree item puts its label into\nthe always-open expert slot of its embedded link — carries segments but no sentinel, so it binds\n`labelLangSegmentsProp`.\n\nThis rule binds new and changed props immediately. Existing props adopt it family by family — prop\ndefinitions first, then component signatures. Where no named schema type exists yet, it is added: an\nadditive, non-breaking change, because naming a type never changes its structure.\n\n#### Label Handling Forms\n\nSix forms govern how a label value flows through the layers. They exist because the validation\nboundary and the render boundary are different places: the web component validates untyped input\n(attributes arrive as strings, adapters pass any runtime value), while a functional component\nreceives already-normalized props and never validates.\n\n1. **A functional component trusts its props.** Its prop type comes from the props config slot\n (`required` → mandatory, `optional` → partial). A guard inside a functional component is never a\n distrust of validation — it handles the documented \"not set\" state of an optional prop (the alert\n without a label renders no heading).\n2. **The \"not set\" guard is `label?.length > 0`** for optional `string | LabelSegment[] | undefined`\n labels, in JSX conditions and ternaries alike. The expression must be strictly boolean: a bare\n `label?.length &&` renders the digit `0` into the DOM when the label is the empty string.\n3. **`trimLabel(label)` is the only way to obtain a plain string** (accessible names, aria-label,\n aria-description). `trimLabel` is undefined-safe by signature (`undefined` → `''`) and the only\n place joining segment arrays — call it without `?? ''` or `|| ''`, and never apply string\n operations to a segment array directly.\n4. **`''` is the expert-slot sentinel, everywhere.** Only components with `labelWithExpertSlotProp`\n accept it; their span switches to the expert slot. Everywhere else it is an invalid value. The\n one mapping to \"not set\" lives where an empty label is legitimate input (the tooltip behavior:\n `apply(value || undefined, …)`, mapping `''` to the unset state instead of an invalid-value\n warning).\n5. **Rendered labels go through `renderLabelWithLang`** so each segment keeps its `lang` attribute\n for screen readers. A pure `aria-label` uses `trimLabel` — language segments would have no\n effect there, which is why landmark components bind `labelProp`.\n6. **Which prop definition a component binds follows its markup** (see the variant rule above);\n the forms here stay identical for all three label definitions.\n\n#### `PropDefinition<TInternal>`\n\n`PropDefinition<TInternal>` defines `normalize` (unknown → TInternal), `validate` (TInternal → boolean), `getDefaultValue()` (→ TInternal) and `apply(value, callback)`. The normalize function accepts `unknown` because HTML attributes can arrive as any type.\n\nEach `PropDefinition` provides an `apply(value, callback)` method that combines normalization, validation and fallback handling into a single call. If the value is `undefined` or `null`, the built-in default is used. Otherwise, the value is normalized and validated before being passed to the callback — ensuring callbacks only receive type-safe internal values:\n\n```typescript\nmaxProp.apply(value, (normalized) => {\n\t// normalized is number, type-safe and validated (> 0)\n\tthis.setRenderProp('max', normalized);\n});\n```\n\n##### Undefined handling, requiredness and the default contract\n\nThree rules separate the layers, so a fachliche validator never has to deal with \"not set\":\n\n1. **Requiredness is a property of the component, decided by the props config slot.** The `required`/`optional` arrays feed `ApiFromConfig` (`Props.Required`/`Props.Optional`) _and_ drive the runtime warning: `BaseWebComponent.isRequired(key)` answers from the `required` array, and the applying watcher passes it to `apply` as its third argument (`labelProp.apply(value, cb, this.isRequired('label'))`). A prop definition itself carries no requiredness — one definition serves a required prop in one component (the link's `href`) and an optional one in another (the card's) without duplication. Appliers outside a component config (items, behaviors, `resolve-props`) apply without the argument: an unset value there is a legitimate \"not set\", not a missing required value.\n2. **`apply()` intercepts `undefined` and `null` before any fachliche validation**: after the warning when `required` was passed, the built-in default is substituted and handed to the callback. `normalize` and `validate` never see a raw `undefined` from the `apply` path.\n3. **A definition with a default must accept it as a value; a definition without a default has no fallback at all.** `createPropDefinition` takes `undefined` as a deliberate \"no default\": an unset value then flows through as \"not set\" — nothing is validated, the validator only ever sees real values (e.g. `isValidLabel` checks length only). A definition that does carry a default has its fallback validated and throws on an invalid one. Either way the fachliche validation of real values stays untouched by the \"not set\" state. The factory types this guarantee: a definition created with a default exposes a non-optional `getDefaultValue(): TInternal` (`PropDefinitionWithDefault`), so callers read the fallback without assertions.\n\n#### `DependentPropDefinition<TInternal, TDeps>`\n\nSome props require context from other props to normalize or validate correctly. `createDependentPropDefinition` extends the pattern with a `TDeps` parameter passed through to both `normalize` and `validate`. Its `apply` method takes the deps object as a third argument:\n\n```typescript\nclampedNumberValueProp.apply(\n\tvalue,\n\t(normalized) => {\n\t\tthis.setRenderProp('value', normalized);\n\t},\n\t{ min: 0, max: this.getRenderProp('max') },\n);\n```\n\n#### Type Extraction\n\n`InternalOf<P>` and `ExternalOf<P>` utility types extract the correct type for each architectural layer automatically:\n\n| Layer | Type Extractor | Example (`ColorProp`) |\n| -------------------- | -------------- | --------------------- |\n| WC `@Prop` | `ExternalOf` | `ColorPair \\| string` |\n| `@Watch` handler | `ExternalOf` | `ColorPair \\| string` |\n| WC `setRenderProp` | `InternalOf` | `ColorPair` |\n| WC `getRenderProp` | `InternalOf` | `ColorPair` |\n| Functional Component | `InternalOf` | `ColorPair` |\n\n### API Definition with `PropsConfigShape` and `ApiFromConfig`\n\nComponent APIs are defined using a runtime props config object (`PropsConfigShape`) that groups prop definitions into `required` and `optional` arrays. The `ApiFromConfig<Config, Extra>` utility type derives the full `ComponentApi` type from this config, making the props config the single source of truth for both runtime behaviour (normalization, validation, defaults) and compile-time types:\n\n```ts\nexport const skeletonPropsConfig = {\n\trequired: [nameProp],\n} as const satisfies PropsConfigShape;\n\nexport type SkeletonApi = ApiFromConfig<\n\ttypeof skeletonPropsConfig,\n\t{\n\t\tCallbacks: { click: () => void };\n\t\tEmitters: { loaded: number; rendered: void };\n\t\tMethods: { focus: () => void; toggle: () => void };\n\t\tStates: { count: number; label: string; show: boolean };\n\t}\n>;\n```\n\n`ApiFromConfig` automatically merges the phantom prop types from the config arrays into the `Props.Required` and `Props.Optional` fields. The WC declares the same config object as its `propsConfig` field, from which the base derives the initial render-prop defaults.\n\nThe contracts between layers are formalized through TypeScript interfaces in [`generic-types.ts`](../../internal/functional-components/generic-types.ts). These generics (`WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps`) guarantee that components share a consistent shape for props, callbacks, emitters and refs.\n\n### Methods and Automatic Promise Wrapping\n\nStencil requires that all public `@Method()` decorated methods return a `Promise`. To keep API definitions concise, `ComponentApi` allows method signatures to be defined with plain return types. The `PromiseMethod<Methods>` utility type automatically wraps each method's return type in `Promise<T>` via `WebComponentInterface`:\n\n```ts\n// API definition — simple, no Promise required\nMethods: {\n focus: () => void;\n getValue: () => number;\n};\n```\n\n```ts\n// Resolved in WebComponentInterface — automatically Promise-wrapped\nfocus: () => Promise<void>;\ngetValue: () => Promise<number>;\n```\n\n`BehaviorInterface` intentionally does **not** apply `PromiseMethod` wrapping — Behaviors stay synchronous and testable, and the `async`/`Promise.resolve()` wrapping happens at the WC layer.\n\n### Event Handler Policy\n\nWC and Behavior methods follow a clear convention based on their usage pattern:\n\n- **Callbacks, event handlers, and ref setters** are declared as **arrow class properties** (`handleClick = () => { … }`). This auto-binds them to the instance, so they can be safely passed as references without `.bind(this)` or wrapper arrows.\n- **Lifecycle methods, watchers, and public API methods** (`componentWillLoad`, `watchName`, `focus`, `toggle`) remain **prototype methods** shared across all instances for memory efficiency.\n\nBecause callbacks are already arrow properties, both render patterns are valid:\n\n```tsx\n// Pattern A: Pass arrow property directly (concise)\n<ClickButtonFC handleClick={this.handleClick} refButton={this.setButtonRef} />\n\n// Pattern B: Wrap in arrow for explicit forwarding (allows intermediate logic)\n<SkeletonFC handleClick={() => this.handleClick()} refButton={(el) => this.setButtonRef(el)} />\n```\n\n#### ⚠️ Never use `.bind(this)` with `addEventListener`/`removeEventListener`\n\nArrow function properties automatically bind `this` at definition time. **Never** create new bound instances with `.bind(this)` in DOM event registration, as this causes listener accumulation and memory leaks — `addEventListener` and `removeEventListener` must receive the **exact same function reference** to match. Use an arrow property, or a ref callback that removes the old listener before adding the new one (see `src/components/popover-button/base.tsx`, `handleToggle` + `componentDidRender`/`disconnectedCallback`).\n\n### Implementation Flow\n\n1. **Initialisation** – the base seeds the render-prop store with the defaults of `propsConfig` on the first access — earliest possible point is a `@Watch` fired by a prop assignment before `componentWillLoad`. `componentWillLoad` applies the current prop snapshot, ensuring render props reflect external values before the first render. Composed Behaviors are initialized here too.\n2. **Prop updates** – `@Watch` handlers receive raw values, normalize/validate them via schema helpers, and store the result with `setRenderProp`.\n3. **Rendering** – the WC reads render props via `getRenderProp` and feeds them into the FC.\n4. **User interaction** – the FC emits DOM events / calls callbacks. The WC wires these back into its own handlers (or Behavior methods) so state transitions remain encapsulated.\n\n### Props Pattern\n\nA critical design principle is that **functional components always render using Props**, which are either:\n\n1. **Normalized and validated external props** — incoming props processed through schema helpers\n2. **Internal component state** — derived or computed values managed by the WC via `@State`\n\nThis ensures the renderer never works with raw, unvalidated data. Props must always be initialized before being passed to the FC (the seeding from `propsConfig` on the first access guarantees this).\n\n### Watcher Example\n\nIncoming props are normalized in dedicated watchers directly inside the WC:\n\n```ts\n// Prop definition (internal/props/name.ts); NamePropType is imported from schema/props/name.ts\ntype NameProp = SimpleProp<'name', NamePropType>;\nconst nameProp = createPropDefinition<NameProp>('name', '', normalizeString);\n```\n\n```tsx\n// Web Component (src/components/<component>/component.tsx)\n@Prop() public _name!: NamePropType;\n\n@Watch('_name')\npublic watchName(value?: NamePropType): void {\n\tnameProp.apply(value, (v) => this.setRenderProp('name', v));\n}\n```\n\nThe `apply()` method uses the default value built into `nameProp` when the incoming value is `undefined` or `null`.\n\n### WC State Management\n\nThe WC manages two kinds of state directly:\n\n**Normalized Props** (via `setRenderProp()`):\n\n- Stored in the render-prop map after validation\n- Updated by watchers (e.g. `watchName`)\n- Never trigger Stencil re-renders on their own\n- Retrieved via `getRenderProp(key)` for rendering\n\n**Derived/Managed State** (via `@State` + `setState()`/`getState()`):\n\n- Stored in `@State` fields on the WC\n- Used for computed or UI state (e.g. `count`, `show`, `ariaCurrent`)\n- Each `setState()` assignment triggers a Stencil re-render\n- Read back with `getState(key)`\n\n**Rule**: a prop watcher should call `setRenderProp()` to store the normalized value. Add a `setState()` call only for `@State` fields that require reactive updates. This minimizes re-renders while keeping code clear:\n\n```tsx\n@Watch('_name')\npublic watchName(value?: string): void {\n\tnameProp.apply(value, (v) => {\n\t\tthis.setRenderProp('name', v); // Store normalized prop (no re-render)\n\t\t// this.setState('name', v); // Add only if 'name' is also an @State field\n\t});\n}\n```\n\n### WC Initialization\n\nThe WC declares its props config as the `propsConfig` field; the base seeds the render-prop store from it on the first access. `componentWillLoad` applies the current prop values and initializes composed Behaviors:\n\n```tsx\n// Web Component\nprotected readonly propsConfig: PropsConfigShape = skeletonPropsConfig;\n\npublic componentWillLoad(): void {\n\tnameProp.apply(this._name, (v) => this.setRenderProp('name', v));\n\tthis.tooltipBehavior.componentWillLoad({ label: this.getTooltipLabel(), align: this.getRenderProp('tooltipAlign') });\n}\n```\n\n## 5. Building Block View\n\n```mermaid\nclassDiagram\n direction LR\n class WebComponent {\n +componentWillLoad()\n +watchName()\n +render()\n #setState(key, value)\n #getState(key)\n #setRenderProp(key, value)\n +getRenderProp(key)\n }\n class TooltipBehavior {\n +componentWillLoad(props)\n +watchLabel(value)\n +watchAlign(value)\n +getRenderProp(key)\n }\n class LinkFC {\n +render(props)\n }\n class SchemaHelpers {\n +nameProp.apply()\n +labelProp.apply()\n }\n WebComponent ..> SchemaHelpers : normalizes via\n WebComponent --> LinkFC : renders with render props\n WebComponent o--> TooltipBehavior : composes, optional\n```\n\n**Web Component** — implements `WebComponentInterface`, owns the lifecycle, normalizes props, manages reactive state, composes optional Behaviors, and renders the FC.\n\n**TooltipBehavior** — implements `BehaviorInterface`, encapsulates a single reusable concern (tooltip show/hide, listener syncing, positioning). Composed by any WC that needs it.\n\n**LinkFC** — implements `FunctionalComponentProps`, receives the render props and produces JSX without touching state.\n\n**Schema helpers** — provide deterministic data normalization and validation functions reused across all WCs.\n\n## 6. Runtime View\n\nThe following sequence demonstrates how an external update is normalized and validated before it propagates to the renderer. The WC handles normalization directly — there is no intermediate layer.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant WC as WebComponent\n participant FC as FunctionalComponent\n participant S as Schema\n U->>WC: set attribute _name=\"Alice\"\n WC->>S: nameProp.apply(\"Alice\", callback)\n S->>S: normalize(\"Alice\") → \"Alice\"\n S->>S: validate(\"Alice\") → true\n S-->>WC: callback(\"Alice\")\n WC->>WC: setRenderProp('name', \"Alice\")\n WC->>FC: render(renderProps)\n FC-->>WC: markup\n WC-->>U: updated DOM\n Note over S,WC: apply() combines normalize + validate + callback\n Note over WC,FC: renderProps contain normalized/validated data or @State\n```\n\nThis runtime view highlights how the WC normalizes and validates external values before any rendering occurs. Only after the WC updates its render props does it invoke the functional component, patch the returned markup and expose the updated DOM to the user.\n\n## 7. Deployment View\n\nThe skeleton ships as part of the `@public-ui/components` package. During build the Stencil compiler produces framework-agnostic bundles ready for distribution via npm or CDN.\n\n## 8. Cross-cutting Concepts\n\n| Concept | Description |\n| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Composition over inheritance** | WCs compose Behaviors (e.g. `TooltipBehavior`) for reusable logic rather than relying on inheritance. |\n| **Orchestrator WC** | The WC is the single orchestrator: it normalizes props, manages state, and renders. No controller/aspect class sits between the element and the FC. |\n| **BemRootNodeFC pattern** | FCs render a single root `<div>` via `BemRootNodeFC`, with a type-checked `block` and `modifiers`. Produces `<div class=\"kol-block kol-block--…\">`; inner elements use BEM element classes. |\n| **Embedded components through items** | A component that embeds another component in its own shadow DOM renders that component's FC directly; an item (`createButtonItem`, …) owns the orchestration of each embedded instance. |\n| **Declarative rendering** | Functional components are pure and stateless. |\n| **Event-driven communication** | User interaction is emitted as DOM events/callbacks rather than calling functions across layers. |\n| **Props Pattern** | Functional components exclusively receive Props that contain either normalized/validated external data or internal component state. Props must always be initialized. |\n| **Shadow DOM First** | WCs use `shadow: true`; `shadow: false` is reserved for the transitional pattern. Components that never need an element wrapper are plain FCs. |\n| **ARIA ID Uniqueness via readable nonce IDs** | Any DOM `id` referenced by ARIA attributes (e.g. `aria-controls`, `aria-labelledby`) must be unique per component instance and follow the pattern `readable-identifier-<nonce>`. Use `private readonly someId = createUniqueId('readable-identifier')` from `utils/dev.utils`. This prevents ID collisions when components are composed inside a shared DOM scope (e.g. multiple WC instances within one shadow root, or direct light-DOM usage). Shadow DOM alone is not sufficient when a shadow component renders multiple instances of an internal WC in the same shadow root. |\n| **State ownership** | The WC owns reactive state (`@State`) and render props; the FC consumes them. |\n| **Type safety** | `WebComponentInterface`, `BehaviorInterface` and `FunctionalComponentProps` encode compile-time contracts between layers. |\n| **Explicit schema types** | Every prop has exactly one named schema type in `src/schema/props`; prop definitions, `@Prop` declarations, watchers and apply methods reference that name instead of inlining native types (the stenciljs/core#4663 alias caveat is confined to the jest toolchain). |\n| **Styling boundary** | A component's `style.scss` is base styling: layout and structure only, no colors (except the black/white contrast fallback), no spacing and no dark/light color scheme (`prefers-color-scheme`, `color-scheme`, `light-dark()`). Colors, spacing and color schemes are implemented in the theme packages. See [`docs/BASE_STYLING_VS_THEMING_CONCEPT.md`](../../../../../docs/BASE_STYLING_VS_THEMING_CONCEPT.md). |\n| **Watcher placement** | Attach `@Watch` only to underscored public props (e.g. `_name`); internal state fields use `@State`. |\n\n## 9. Design Decisions\n\n1. **Eliminate the Aspect layer**\n - _Previous architecture_: a separate `BaseAspect` class sat between the WC and the FC (`WC → Aspect → FC`).\n - _Reason_: the relationship was strictly 1 WC : 1 Aspect, so the Aspect was pure indirection — every watcher and render-prop access was a pass-through. The WC can manage render props directly (the base seeds them from the declared `propsConfig` field on first access; reads and writes go through `getRenderProp`/`setRenderProp` on `BaseWebComponent`). Removing the layer halves the number of classes per component, removes a constructor/`StateAccess` handoff, and keeps the data flow in one place. Only genuinely composable, cross-component logic survives as a `Behavior`.\n2. **Behaviors for genuinely shared logic only**\n - _Alternative_: also extract per-component logic into a dedicated behavior/controller.\n - _Reason_: a Behavior earns its existence only when the same logic is reused across multiple components (e.g. `TooltipBehavior`). Single-use logic stays as private methods on the WC.\n3. **Underscored public props**\n - _Alternative_: mirror external props directly without underscores.\n - _Reason_: underscores make the separation between public API and internal state explicit.\n4. **Shadow DOM enabled for web components (shadow: true)**\n - _Alternative_: allow some components to have `shadow: false`.\n - _Reason_: Shadow DOM ensures consistent style isolation and prevents CSS conflicts from host page styles, eliminating a category of hard-to-debug styling issues.\n5. **Embedded components render their FC through items**\n - _Alternative_: render a `shadow:false` element (`kol-button-wc`, …) inside the embedding component's shadow DOM, so its stylesheet reaches the inner `.kol-…` classes.\n - _Reason_: such an element duplicates the orchestrator of the public element and puts an extra node between the embedding component and the embedded block. An item keeps one orchestration per embedded instance in the embedding WC and renders the FC root in place of the element.\n6. **Centralised validation in the WC**\n - _Alternative_: perform validation scattered inside prop watchers without schema helpers.\n - _Reason_: routing all external values through `PropDefinition.apply()` keeps validation, defaults and normalization in one reusable, testable place.\n7. **Functional component rendering**\n - _Alternative_: render JSX directly inside the web component class.\n - _Reason_: a pure renderer improves testability and eliminates side effects.\n8. **Generic interface contracts**\n - _Alternative_: rely on ad-hoc typing per component.\n - _Reason_: shared interfaces keep props, callbacks, emitters and refs uniform across components, making WCs, Behaviors and renderers interchangeable.\n9. **@State for managed UI state, render props for normalized props**\n - _Pattern_: public props (e.g. `_name`) are normalized and stored as render props. UI state that is managed but not exposed as props (like `count`, `show`, `ariaCurrent`) uses `@State` to trigger reactive re-renders.\n - _Reason_: normalized props do not need `@State` — they are held as render props and accessed via `getRenderProp(key)`. This avoids unnecessary re-rendering while keeping reactive state explicit.\n10. **Host element without redundant class attribute**\n - _Alternative_: add the component name as a class attribute to `<Host>` (e.g. `<Host class=\"kol-abbr\">`).\n - _Reason_: the tag name alone (e.g. `<kol-abbr>`) plus Shadow DOM are sufficient for styling and identification. The BEM root class is emitted by `BemRootNodeFC` inside the FC, not on `<Host>`.\n11. **Omit unused API fields in ComponentApi definitions**\n - _Pattern_: all fields in `ComponentApi` are optional except `States` (`Props`, `Emitters`, `Methods`, `Callbacks`, `Refs`, `Listeners` — `States` is required and defaults to `Record<never, never>` via `ApiFromConfig`). Only define the fields the component actually uses. The generic type extraction in `generic-types.ts` safely defaults missing fields to empty records.\n - _Alternative_: define all fields explicitly, using empty records for unused ones.\n - _Reason_: a minimal API definition is easier to read and accurately conveys what the component does.\n12. **ARIA ID uniqueness via `createUniqueId()`**\n - _Pattern_: any `id` referenced by an ARIA relation attribute must be unique per instance. Declare stable base ids as `private readonly xId = createUniqueId('x')` and derive related ids with `createRelatedUniqueId(baseId, 'control')`.\n - _Alternative_: hardcode a static string.\n - _Reason_: Shadow DOM scopes IDs per shadow root, but a parent may render multiple instances of an internal WC in the same shadow root, colliding IDs. `createUniqueId()` is cheap and eliminates this category of bug, and also covers direct light-DOM usage.\n13. **No `data-testid` — use BEM class selectors in tests**\n - _Pattern_: do not add `data-testid` attributes. Tests select elements via their BEM class names (`page.locator('.kol-component__element')`).\n - _Alternative_: add `data-testid` and use `getByTestId()`.\n - _Reason_: BEM class names are already present, stable, and semantically tied to the component. Using them keeps production markup clean of test-only concerns.\n14. **Test co-location — all tests live next to the component**\n - _Pattern_: all test files sit directly alongside `component.tsx` — snapshot tests (`snapshot.spec.tsx`, Jest) and interaction tests (`interaction.e2e.ts`, Playwright). File names are uniform across components.\n - _Alternative_: group tests into a dedicated `test/` subdirectory.\n - _Reason_: co-located tests are easier to discover and keep related files visible side-by-side.\n15. **Public API parity during migration — the FC face is not the public face**\n - _Pattern_: a skeleton migration keeps the WC's public `@Prop`/`@Method` set byte-identical to the predecessor: same members, same schema-alias types, same defaults, same JSDoc (including `@deprecated`). The WC implements the schema `*Props` interface alongside `WebComponentInterface<Api>` so drift fails the build. Internal FC props without a public predecessor prop stay internal (fed from defaults, no public `@Prop` added).\n - _Alternative_: expose every FC prop 1:1 as a public `@Prop` and declare props with the internal primitive types.\n - _Reason_: the public API is a compatibility contract (adapters, IntelliSense, `custom-elements.json` are generated from `prop.docs`/`method.docs`). Growing it silently (e.g. link gained `_ariaOwns`, `_customClass`, `_tabIndex`, `click()`) or dropping its documentation is a breaking change disguised as a refactor. See [§4 Public API Contract](#public-api-contract-migration-parity).\n16. **Shared orchestrator base for tag variants of one FC**\n - _Pattern_: elements that render the same FC (`kol-button`/`kol-button-link`/`kol-split-button`, `kol-link`/`kol-link-button`) share an abstract, decorator-free base class next to the element (`button/base.tsx`, `link/base.tsx`) that extends `BaseWebComponent<Api>` and holds Behaviors, handlers, `apply<Prop>()` methods and the FC render call. The concrete element declares the Stencil members and delegates from its watchers and lifecycle methods.\n - _Alternative_: copy the orchestrator into every element (the state before this decision: ~350 identical lines in `component.tsx` and `wc.tsx`), or let the variants instantiate a `shadow:false` twin of the public element.\n - _Reason_: the base is not a layer between WC and FC (decision 1 stays intact) — it _is_ the WC's implementation, written once. Stencil only reads decorators and lifecycle hooks from the component class itself, so those stay there; plain methods and fields are inherited at runtime like the ones of `BaseWebComponent`. Anything that needs the host element (e.g. the form-association controller) is created from the concrete constructor after `super()`, because Stencil registers the host at the start of the component class's constructor.\n17. **DOM structure and BEM classes are a theming contract, not public API**\n - _Pattern_: a change of the internal DOM structure or of the BEM classes it needs ships in at least a minor release as a **theming breaking change**: release label `release:theming`, old and new classes listed in the pull request, all themes of this repository adapted in the same change. See [Theming Contract](#theming-contract-shadow-dom-structure-and-bem-classes).\n - _Alternative_: treat every class or node change as a breaking change that waits for the next major release.\n - _Reason_: themes can be adapted to such a change largely automatically through their own visual snapshots and the zero-visual-delta workflow. Holding back structural cleanups (single BEM root, registered classes) until a major release would keep known non-conformities alive for a long time without protecting anyone more than the changelog entry does.\n18. **Explicit schema types per prop**\n - _Pattern_: every prop's value type is the named schema type from `src/schema/props`; the prop bag, the prop definition in `internal/props`, the `@Prop` declaration, the watcher and the apply method all reference that name, and no layer inlines a native type. See [Explicit Schema Types per Prop](#explicit-schema-types-per-prop).\n - _Alternative_: type prop definitions and component signatures with bare natives (`SimpleProp<'disabled', boolean>`) and keep the schema name only on the prop bag.\n - _Reason_: the type is defined once and every layer points at the same name, so drift between the layers fails the compiler instead of surfacing in review; apply and watcher signatures carry the domain term; and the prop definitions binding one render key are connected by their shared schema type, not only by the key string. Naming a type never changes its structure, so adopting it is invisible to consumers. The pinned Stencil's un-coerced attribute parsing for imported aliases (stenciljs/core#4663) is a known test-toolchain caveat, not a reason to inline natives.\n\n## 10. Quality Requirements\n\n- Maintainability: the WC is the single orchestrator, reducing the number of classes and the cost of change.\n- Reliability: schema helpers validate every external value before it mutates state.\n- Testability: the FC is a pure renderer and can be unit tested in isolation; Behaviors can be tested standalone. Snapshot tests (Jest) verify DOM output; interaction tests (Playwright) verify user-facing behaviour.\n- Performance: **optimized re-rendering** — public props are normalized and stored as render props (no re-render); only `@State` changes trigger re-renders. Stencil batches simultaneous prop/state changes into a single re-render.\n- Accessibility: follow repository-wide a11y presets and prefer `KolTooltip` over `title` attributes.\n- Security: avoid direct DOM injection; rely on typed props and validation to prevent XSS.\n\n## 11. Risks and Technical Debt\n\n- The transitional `shadow:false` WCs are temporary scaffolding; they should be removed as consumers migrate to render FCs directly.\n- WCs with many props can accumulate verbose watcher boilerplate; the `PropDefinition.apply()` pattern keeps each watcher to one line, but a component with dozens of props still produces dozens of watchers.\n- Behaviors that hold listener references must clean up in `disconnectedCallback` to avoid leaks (see the Event Handler Policy warning).\n\n## 12. Glossary\n\n| Term | Definition |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| **BEM** | Block Element Modifier naming convention for CSS class names. |\n| **BemRootNodeFC** | Single-root BEM wrapper FC. Renders one `<div class=\"kol-block kol-block--…\">` from a type-checked `block` and `modifiers`. |\n| **Behavior** | Optional, composable unit of reusable logic living inside a WC; extends `BaseBehavior`. Example: `TooltipBehavior`. |\n| **Orchestrator (WC)** | The web component, which directly owns lifecycle, prop normalization, state management, Behavior composition and rendering. |\n| **Functional Component** | Pure renderer without side effects that exclusively works with Props. |\n| **Props** | Normalized and validated props or internal state passed to functional components. Must always be initialized. |\n| **Render props** | Validated, normalized prop values stored on the WC via `setRenderProp` and read via `getRenderProp` for rendering. |\n| **Schema Helper** | Utility providing `normalize` (unknown → TInternal), `validate` (TInternal → boolean) and `apply` (normalize + validate + callback) for props. |\n| **Schema Type** | Named value type of one prop in `src/schema/props` (e.g. `DisabledPropType`); the single spelling every layer references. |\n| **StateAccess** | `{ setState, getState }` bundle a WC passes to a Behavior; `BaseWebComponent.stateLess` is the no-op sentinel for stateless Behaviors. |\n| **Stencil** | Compiler for building framework-agnostic web components. |\n| **Transitional WC** | A `shadow:false` WC that renders an FC into the light DOM so legacy consumers can reach inner BEM classes; deleted once consumers migrate. |\n| **Watch Decorator** | Stencil decorator (`@Watch`) that observes prop changes. |\n",
|
|
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",
|
|
3640
3681
|
"kind": "spec"
|
|
3641
3682
|
},
|
|
3642
3683
|
{
|
|
@@ -3920,7 +3961,7 @@
|
|
|
3920
3961
|
"group": "spec",
|
|
3921
3962
|
"name": "pagination",
|
|
3922
3963
|
"path": "packages/tools/mcp/node_modules/@public-ui/components/doc/pagination.md",
|
|
3923
|
-
"code": "# kol-pagination\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property
|
|
3964
|
+
"code": "# kol-pagination\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_boundaryCount` | `_boundary-count` | Defines the amount of pages to show next to the outer arrow buttons. | `number \\| undefined` | `1` |\n| `_customClass` | `_custom-class` | Defines the custom class attribute if _variant=\"custom\" is set. | `string \\| undefined` | `undefined` |\n| `_hasButtons` | `_has-buttons` | Defines which navigation buttons to render (first, last, next, previous buttons). | `boolean \\| string \\| undefined \\| { first: boolean; last: boolean; next: boolean; previous: boolean; }` | `true` |\n| `_label` | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `string \\| undefined` | `undefined` |\n| `_max` _(required)_ | `_max` | Defines the maximum value of the element. | `number` | `undefined` |\n| `_on` _(required)_ | -- | Gibt an, auf welche Callback-Events reagiert werden. | `{ onChangePage?: EventValueOrEventCallback<Event, number> \\| undefined; onChangePageSize?: EventValueOrEventCallback<Event, number> \\| undefined; onClick?: EventValueOrEventCallback<Event, number> \\| undefined; }` | `undefined` |\n| `_page` _(required)_ | `_page` | Defines the current page. | `number` | `undefined` |\n| `_pageSize` | `_page-size` | Defines the amount of entries to show per page. | `number` | `1` |\n| `_pageSizeOptions` | `_page-size-options` | Defines the options for the page-size-select. | `number[] \\| string` | `[]` |\n| `_siblingCount` | `_sibling-count` | Defines the amount of pages to show next to the current page. | `number \\| undefined` | `1` |\n| `_tooltipAlign` | `_tooltip-align` | Defines where to show the Tooltip preferably: top, right, bottom or left. | `\"bottom\" \\| \"left\" \\| \"right\" \\| \"top\" \\| undefined` | `'top'` |\n\n\n----------------------------------------------\n\n\n",
|
|
3924
3965
|
"kind": "spec"
|
|
3925
3966
|
},
|
|
3926
3967
|
{
|
|
@@ -3968,6 +4009,15 @@
|
|
|
3968
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",
|
|
3969
4010
|
"kind": "spec"
|
|
3970
4011
|
},
|
|
4012
|
+
{
|
|
4013
|
+
"id": "spec/skeleton",
|
|
4014
|
+
"group": "spec",
|
|
4015
|
+
"name": "skeleton",
|
|
4016
|
+
"description": "Focuses the interactive element of the component.",
|
|
4017
|
+
"path": "packages/tools/mcp/node_modules/@public-ui/components/doc/skeleton.md",
|
|
4018
|
+
"code": "# kol-skeleton\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| -------------------- | --------- | ---------------------------------------- | -------- | ----------- |\n| `_name` _(required)_ | `_name` | Sets the name of the skeleton component. | `string` | `undefined` |\n\n\n## Events\n\n| Event | Description | Type |\n| ---------- | --------------------------------------------------------------- | --------------------- |\n| `loaded` | Emitted when the skeleton has finished loading. | `CustomEvent<number>` |\n| `rendered` | Emitted when the skeleton has been rendered for the first time. | `CustomEvent<void>` |\n\n\n## Methods\n\n### `focus(options?: KolFocusOptions) => Promise<void>`\n\nFocuses the interactive element of the component.\n\n#### Parameters\n\n| Name | Type | Description |\n| --------- | ------------------------------ | ----------- |\n| `options` | `KolFocusOptions \\| undefined` | |\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n### `toggle() => Promise<void>`\n\nToggles the visibility of the skeleton component.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
|
|
4019
|
+
"kind": "spec"
|
|
4020
|
+
},
|
|
3971
4021
|
{
|
|
3972
4022
|
"id": "spec/skip-nav",
|
|
3973
4023
|
"group": "spec",
|
|
@@ -4000,7 +4050,7 @@
|
|
|
4000
4050
|
"name": "table-stateful",
|
|
4001
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.",
|
|
4002
4052
|
"path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateful.md",
|
|
4003
|
-
"code": "# kol-table-stateful\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Overview\n\nThe **Table** component is primarily used for the clear presentation of data sets. It is designed to automatically determine all data-dependent values and render the table accordingly. This includes optional features such as column sorting and pagination.\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_allowMultiSort` | `_allow-multi-sort` | Defines whether to allow multi sort. | `boolean \\| undefined` | `undefined` |\n| `_ariaLabelledby` | `_aria-labelledby` | References an external element by ID that serves as the accessible label for this table. Uses ElementInternals.ariaLabelledByElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS) — use `_label` instead. | `string \\| undefined` | `undefined` |\n| `_data` _(required)_ | `_data` | Defines the primary table data. | `KoliBriTableDataType[] \\| string` | `undefined` |\n| `_dataFoot` | `_data-foot` | Defines the data for the table footer. | `KoliBriTableDataType[] \\| string \\| undefined` | `undefined` |\n| `_fixedCols` | -- | Defines the fixed number of columns from start and end of the table | `[number, number] \\| undefined` | `undefined` |\n| `_hasSettingsMenu` | `_has-settings-menu` | Enables the settings menu if true (default: false). | `boolean \\| undefined` | `undefined` |\n| `_headers` _(required)_ | `_headers` | Defines the horizontal and vertical table headers. | `string \\| { horizontal?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; vertical?: KoliBriTableHeaderCellWithLogic[][] \\| undefined; }` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string` | `undefined` |\n| `_loading` | `_loading` | Wether the table shows a loading spinner (default: false). | `boolean \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for table events. | `undefined \\| { onSelectionChange?: EventValueOrEventCallback<Event, StatefulSelectionChangeEventPayload> \\| undefined; }` | `undefined` |\n| `_pagination` | `_pagination` | Defines whether to show the data distributed over multiple pages. | `boolean \\| string \\| undefined \\| { _page: number; } & { _on?: KoliBriPaginationButtonCallbacks \\| undefined; _page?: number \\| undefined; _label?: string \\| undefined; _max?: number \\| undefined; _boundaryCount?: number \\| undefined; _hasButtons?: boolean \\| Stringified<PaginationHasButton> \\| undefined; _pageSize?: number \\| undefined; _pageSizeOptions?: Stringified<number[]> \\| undefined; _siblingCount?: number \\| undefined; _customClass?: string \\| undefined; _tooltipAlign?: AlignPropType \\| undefined; }` | `undefined` |\n| `_paginationPosition` | `_pagination-position` | Controls the position of the pagination. | `\"both\" \\| \"bottom\" \\| \"top\" \\| undefined` | `'bottom'` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n## Methods\n\n### `getSelection() => Promise<KoliBriTableDataType[] | null>`\n\nReturns the selected rows.\n\n#### Returns\n\nType: `Promise<KoliBriTableDataType[] | null>`\n\n\n\n### `resetSort() => Promise<void>`\n\nResets the sort state to the default values defined in the `_headers` prop.\n\n#### Returns\n\nType: `Promise<void>`\n\n\n\n\n----------------------------------------------\n\n\n",
|
|
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",
|
|
4004
4054
|
"kind": "spec"
|
|
4005
4055
|
},
|
|
4006
4056
|
{
|
|
@@ -4008,7 +4058,7 @@
|
|
|
4008
4058
|
"group": "spec",
|
|
4009
4059
|
"name": "table-stateless",
|
|
4010
4060
|
"path": "packages/tools/mcp/node_modules/@public-ui/components/doc/table-stateless.md",
|
|
4011
|
-
"code": "# kol-table-stateless\n\n\n\n<!-- Auto Generated Below -->\n\n\n## Properties\n\n| Property | Attribute | Description | Type | Default |\n| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |\n| `_ariaLabelledby` | `_aria-labelledby` | References an external element by ID that serves as the accessible label for this table. Uses ElementInternals.ariaLabelledByElements to cross the Shadow DOM boundary. Supported by desktop screen readers (NVDA, JAWS with Chrome/Firefox). Not yet supported by mobile screen readers (TalkBack, VoiceOver iOS) — use `_label` instead. | `string \\| undefined` | `undefined` |\n| `_data` _(required)_ | `_data` | Defines the primary table data. | `KoliBriTableDataType[] \\| string` | `undefined` |\n| `_dataFoot` | `_data-foot` | Defines the data for the table footer. | `KoliBriTableDataType[] \\| string \\| undefined` | `undefined` |\n| `_fixedCols` | -- | Defines the fixed number of columns from start and end of the table | `[number, number] \\| undefined` | `undefined` |\n| `_hasSettingsMenu` | `_has-settings-menu` | Enables the settings menu if true (default: false). | `boolean \\| undefined` | `undefined` |\n| `_headerCells` | `_header-cells` | <span class=\"text-red-500\">**[DEPRECATED]**</span> Will be removed in the future. Use _headers instead. Defines the horizontal and vertical table headers.<br/><br/> | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }` | `undefined` |\n| `_headers` | `_headers` | Defines the horizontal and vertical table headers. | `string \\| undefined \\| { horizontal?: KoliBriTableHeaderCell[][] \\| undefined; vertical?: KoliBriTableHeaderCell[][] \\| undefined; }` | `undefined` |\n| `_label` _(required)_ | `_label` | Defines the visible or semantic label of the component (e.g. aria-label, label, headline, caption, summary, etc.). | `LabelSegment[] \\| string` | `undefined` |\n| `_loading` | `_loading` | Wether the table shows a loading spinner (default: false). | `boolean \\| undefined` | `undefined` |\n| `_on` | -- | Defines the callback functions for table events. | `undefined \\| { onSort?: EventValueOrEventCallback<MouseEvent, SortEventPayload> \\| undefined; onSelectionChange?: EventValueOrEventCallback<Event, KoliBriTableSelectionKeys> \\| undefined; onChangeHeaderCells?: EventValueOrEventCallback<Event, TableHeaderCells> \\| undefined; }` | `undefined` |\n| `_selection` | `_selection` | Defines how rows can be selected and the current selection. | `string \\| undefined \\| ({ disabledKeys?: KoliBriTableSelectionKeys \\| undefined; keyPropertyName?: string \\| undefined; label: (row: KoliBriTableDataType) => string; multiple?: boolean \\| undefined; selectedKeys?: KoliBriTableSelectionKeys \\| undefined; })` | `undefined` |\n| `_variant` | `_variant` | Defines which variant should be used for presentation. | `string \\| string[] \\| undefined` | `undefined` |\n\n\n----------------------------------------------\n\n\n",
|
|
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",
|
|
4012
4062
|
"kind": "spec"
|
|
4013
4063
|
},
|
|
4014
4064
|
{
|