feat: Refactor focus handling across components to use propagateFocus utility

- Introduced a new utility function `propagateFocus` to manage focus behavior across various components.
- Updated focus methods in components such as KolInputFile, KolInputNumber, KolInputPassword, KolInputRadio, KolInputRange, KolInputText, KolLinkButton, KolLink, KolPopoverButton, KolSelect, KolSingleSelect, KolSkipNav, KolSplitButton, KolTabs, KolTextarea, KolToolbar, KolTree, and KolTreeItem to utilize the new utility for improved focus management.
- Enhanced focus handling in KolPopover and KolTableStateless components to align with the new focus strategy.
- Added visual test routes for new components and scenarios including KolBadge, KolPopoverButton, KolSkipNav, KolSplitButton, KolTableStateless, KolTabs, and KolToolbar.

Author: deleonio

packages/adapters/hydrate/test/__snapshots__/components.spec.js.mocha-snapshot

@@ -203,6 +203,7 @@ Both are functionally equivalent. Pattern A is more concise; Pattern B allows ad
 Arrow 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:
 
 ❌ **Memory Leak — DO NOT DO THIS:**
+
 ```tsx
 private handleToggle(event: Event) { /* ... */ }
 
@@ -217,6 +218,7 @@ disconnectedCallback() {
 ```
 
 ✅ **Correct — Arrow Function Property (already bound):**
+
 ```tsx
 private handleToggle = (event: Event) => { /* ... */ }  // Arrow property — this is bound here
 
@@ -246,6 +248,7 @@ private catchElement = (element?: HTMLElement): void => {
 ```
 
 **Why this matters:**
+
 - `.bind(this)` creates a new function on each call — `addEventListener` and `removeEventListener` must receive the **exact same function reference** to match
 - When references don't match, `removeEventListener` silently fails
 - Listeners accumulate over time, slowing down event handling and creating garbage collection barriers

packages/components/src/components/_skeleton/ARC42.md

@@ -52,8 +52,8 @@ export class KolAccordion implements AccordionAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	private handleOnClick = (event: MouseEvent) => {

packages/components/src/components/accordion/shadow.tsx

@@ -1,4 +1,4 @@
-import { Component, h, Method, Prop, State, Watch } from '@stencil/core';
+import { Component, Element, h, Method, Prop, State, Watch } from '@stencil/core';
 import { SpanFC } from '../../internal/functional-components/span/component';
 import type { BadgeAPI, BadgeStates, FocusableElement, InternalButtonProps, KoliBriIconsProp, LabelPropType, PropColor, Stringified } from '../../schema';
 import { featureHint, handleColorChange, objectObjectHandler, parseJson, setState, validateColor, validateIcons } from '../../schema';
@@ -22,6 +22,7 @@ featureHint(`[KolBadge] Optimierung des _color-Properties (rgba, rgb, hex usw.).
 	shadow: true,
 })
 export class KolBadge implements BadgeAPI, FocusableElement {
+	@Element() private readonly host!: HTMLKolBadgeElement;
 	private bgColorStr = '#000';
 	private colorStr = '#fff';
 	private readonly id = nonce();
@@ -56,7 +57,7 @@ export class KolBadge implements BadgeAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus(): Promise<void> {
-		return Promise.resolve(this.smartButtonRef?.focus());
+		return this.smartButtonRef?.focus(this.host);
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/badge/shadow.tsx

@@ -1,5 +1,5 @@
 import type { JSX } from '@stencil/core';
-import { Component, h, Method, Prop } from '@stencil/core';
+import { Component, Element, h, Method, Prop } from '@stencil/core';
 import { KolButtonWcTag } from '../../core/component-names';
 import type {
 	AccessKeyPropType,
@@ -41,6 +41,7 @@ import type {
 	shadow: true,
 })
 export class KolButtonLink implements ButtonLinkProps, FocusableElement {
+	@Element() private readonly host?: HTMLKolButtonLinkElement;
 	private buttonWcRef?: HTMLKolButtonWcElement;
 
 	private readonly catchRef = (ref?: HTMLKolButtonWcElement) => {
@@ -60,8 +61,8 @@ export class KolButtonLink implements ButtonLinkProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/button-link/shadow.tsx

@@ -12,7 +12,6 @@ import type {
 	ButtonTypePropType,
 	CustomClassPropType,
 	DisabledPropType,
-	FocusableElement,
 	HideLabelPropType,
 	IconsPropType,
 	IdPropType,
@@ -56,6 +55,7 @@ import { SpanFC } from '../../internal/functional-components/span/component';
 import type { AriaHasPopupPropType } from '../../schema/props/aria-has-popup';
 import { validateAccessAndShortKey } from '../../schema/validators/access-and-short-key';
 import clsx from '../../utils/clsx';
+import { propagateFocus } from '../../utils/element-focus';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import { propagateResetEventToForm, propagateSubmitEventToForm } from '../form/controller';
 import { AssociatedInputController } from '../input-adapter-leanup/associated.controller';
@@ -67,7 +67,7 @@ import { AssociatedInputController } from '../input-adapter-leanup/associated.co
 	tag: 'kol-button-wc',
 	shadow: false,
 })
-export class KolButtonWc implements ButtonAPI, FocusableElement {
+export class KolButtonWc implements ButtonAPI {
 	@Element() private readonly host?: HTMLKolButtonWcElement;
 	private buttonRef?: HTMLButtonElement;
 	private tooltipRef?: HTMLKolTooltipWcElement;
@@ -76,13 +76,8 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.buttonRef?.focus();
-				resolve();
-			});
-		});
+	public async focus(host: HTMLElement): Promise<void> {
+		await propagateFocus(host, this.buttonRef);
 	}
 
 	private readonly hideTooltip = () => {
@@ -118,14 +113,14 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 		}
 
 		if (this.host) {
-			dispatchDomEvent(this.host, KolEvent.click, this.state._value);
+			dispatchDomEvent(this.host as HTMLElement, KolEvent.click, this.state._value);
 		}
 	};
 
 	private readonly onMouseDown = (event: MouseEvent) => {
 		this.state?._on?.onMouseDown?.(event);
 		if (this.host) {
-			dispatchDomEvent(this.host, KolEvent.mousedown);
+			dispatchDomEvent(this.host as HTMLElement, KolEvent.mousedown);
 		}
 	};
 
@@ -320,7 +315,7 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 	};
 
 	public constructor() {
-		this.controller = new AssociatedInputController(this, 'button', this.host);
+		this.controller = new AssociatedInputController(this, 'button', this.host as HTMLElement);
 	}
 
 	@Watch('_accessKey')

packages/components/src/components/button/component.tsx

@@ -1,5 +1,5 @@
 import type { JSX } from '@stencil/core';
-import { Component, h, Method, Prop } from '@stencil/core';
+import { Component, Element, h, Method, Prop } from '@stencil/core';
 import { KolButtonWcTag } from '../../core/component-names';
 import type {
 	AccessKeyPropType,
@@ -33,6 +33,7 @@ import type {
 	shadow: true,
 })
 export class KolButton implements ButtonProps, FocusableElement {
+	@Element() private readonly host?: HTMLKolButtonElement;
 	private buttonWcRef?: HTMLKolButtonWcElement;
 
 	private readonly catchRef = (ref?: HTMLKolButtonWcElement) => {
@@ -52,8 +53,8 @@ export class KolButton implements ButtonProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/button/shadow.tsx

@@ -14,6 +14,7 @@ import type {
 	ComboboxAPI,
 	ComboboxStates,
 	DisabledPropType,
+	FocusableElement,
 	HideLabelPropType,
 	HideMsgPropType,
 	HintPropType,
@@ -34,6 +35,7 @@ import type {
 import type { EventDetail } from '../../schema/interfaces/EventDetail';
 import clsx from '../../utils/clsx';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { ComboboxController } from './controller';
 
 /**
@@ -46,8 +48,8 @@ import { ComboboxController } from './controller';
 	},
 	shadow: true,
 })
-export class KolCombobox implements ComboboxAPI {
-	@Element() private readonly host?: HTMLElement;
+export class KolCombobox implements ComboboxAPI, FocusableElement {
+	@Element() private readonly host?: HTMLKolComboboxElement;
 	private refInput?: HTMLInputElement;
 	private refSuggestions: HTMLLIElement[] = [];
 	private _focusedOptionIndex: number = -1;
@@ -67,12 +69,7 @@ export class KolCombobox implements ComboboxAPI {
 	 */
 	@Method()
 	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.refInput?.focus();
-				resolve();
-			});
-		});
+		await propagateFocus(this.host, this.refInput);
 	}
 
 	private toggleListbox = () => {

packages/components/src/components/combobox/shadow.tsx

@@ -36,7 +36,7 @@ import { KolModal } from './modal/shadow';
 import { KolNav } from './nav/shadow';
 import { KolPagination } from './pagination/shadow';
 import { KolPopoverButton } from './popover-button/shadow';
-import { KolPopover } from './popover/component';
+import { KolPopoverWc } from './popover/component';
 import { KolProgress } from './progress/component';
 import { KolQuote } from './quote/component';
 import { KolSelect } from './select/shadow';
@@ -93,7 +93,7 @@ export const COMPONENTS = [
 	KolModal,
 	KolNav,
 	KolPagination,
-	KolPopover,
+	KolPopoverWc,
 	KolProgress,
 	KolPopoverButton,
 	KolQuote,

packages/components/src/components/component-list.ts

@@ -38,8 +38,8 @@ export class KolDetails implements DetailsAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	private toggleTimeout?: ReturnType<typeof setTimeout>;