feat: Enhance focus management across components

- Added `focus` methods to various components to improve accessibility and user experience.
- Implemented `delegateFocus` utility to ensure elements are focused after they are fully initialized and styled.
- Updated components including `KolLink`, `KolPopoverButton`, `KolSelect`, `KolSingleSelect`, `KolSkipNav`, `KolSplitButton`, `KolTabs`, `KolTextarea`, `KolToolbar`, `KolTree`, and `KolTreeItem` to utilize the new focus management.
- Refactored tests and snapshots to validate the new focus behavior.
- Introduced new visual test routes for components with focus capabilities.

Author: deleonio

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

@@ -52,8 +52,10 @@ 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> {
+		if (this.host) {
+			await this.buttonWcRef?.focus(this.host);
+		}
 	}
 
 	private handleOnClick = (event: MouseEvent) => {

packages/components/src/components/alert/component.tsx

@@ -29,7 +29,7 @@ export class KolAlertWc implements AlertAPI {
 	private readonly close = () => {
 		this._on?.onClose?.(new Event('Close'));
 		if (this.host) {
-			dispatchDomEvent(this.host as HTMLElement, KolEvent.close);
+			dispatchDomEvent(this.host, KolEvent.close);
 		}
 	};
 

packages/components/src/components/badge/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,9 @@ export class KolBadge implements BadgeAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus(): Promise<void> {
-		return Promise.resolve(this.smartButtonRef?.focus());
+		if (this.host) {
+			return this.smartButtonRef?.focus(this.host);
+		}
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/button-link/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,10 @@ 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> {
+		if (this.host) {
+			await this.buttonWcRef?.focus(this.host);
+		}
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/button/component.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 { delegateFocus } 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 delegateFocus(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/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,
@@ -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,10 @@ 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> {
+		if (this.host) {
+			await this.buttonWcRef?.focus(this.host);
+		}
 	}
 
 	public render(): JSX.Element {

packages/components/src/components/combobox/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 { delegateFocus } 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 delegateFocus(this.host, this.refInput);
 	}
 
 	private toggleListbox = () => {

packages/components/src/components/details/shadow.tsx

@@ -38,8 +38,10 @@ 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> {
+		if (this.host) {
+			await this.buttonWcRef?.focus(this.host);
+		}
 	}
 
 	private toggleTimeout?: ReturnType<typeof setTimeout>;

packages/components/src/components/form/shadow.tsx

@@ -22,7 +22,7 @@ import { dispatchDomEvent, KolEvent } from '../../utils/events';
 	shadow: true,
 })
 export class KolForm implements FormAPI {
-	@Element() private readonly host?: HTMLKolTextareaElement;
+	@Element() private readonly host?: HTMLKolFormElement;
 	errorListBlock?: HTMLElement;
 	errorListFirstLink?: HTMLElement;
 	private readonly translateErrorListMessage = translate('kol-error-list-message');
@@ -61,7 +61,7 @@ export class KolForm implements FormAPI {
 
 	private readonly setBlockElement = (el?: HTMLElement) => (this.errorListBlock = el);
 
-	private readonly setFirstLinkElement = (el?: HTMLElement) => (this.errorListFirstLink = el);
+	private readonly setFirstLinkElement = (el?: HTMLKolLinkWcElement) => (this.errorListFirstLink = el as HTMLElement);
 
 	private renderErrorList(errorList?: ErrorListPropType[]): JSX.Element {
 		return (

packages/components/src/components/input-checkbox/input-checkbox.e2e.ts

@@ -28,4 +28,52 @@ test.describe(COMPONENT_NAME, () => {
 		await fillAction(page);
 		expect(await getCheckedProperty()).toBe(true);
 	});
+
+	test(`should set focus on the internal input element via focus() method`, async ({ page }) => {
+		await page.setContent(`<kol-input-checkbox _label="Checkbox"></kol-input-checkbox>`);
+
+		const component = page.locator(COMPONENT_NAME);
+		const input = page.locator('input');
+
+		// Call the focus() method on the component
+		await component.evaluate((element: HTMLKolInputCheckboxElement) => element.focus());
+
+		// Verify the input element has focus
+		const isFocused = await input.evaluate((el) => el === document.activeElement || (el.getRootNode() as ShadowRoot | Document).activeElement === el);
+		expect(isFocused).toBe(true);
+	});
+
+	test(`should delegate focus to internal input when clicking on host element (delegatesFocus)`, async ({ page }) => {
+		await page.setContent(`<button>Before</button><kol-input-checkbox _label="Checkbox"></kol-input-checkbox><button>After</button>`);
+
+		const component = page.locator(COMPONENT_NAME);
+		const input = page.locator('input');
+
+		// Click on the component host element
+		await component.click();
+		await page.waitForChanges();
+
+		// Verify the internal input has focus
+		const isFocused = await input.evaluate((el) => el === document.activeElement || (el.getRootNode() as ShadowRoot | Document).activeElement === el);
+		expect(isFocused).toBe(true);
+	});
+
+	test(`should allow Tab navigation to reach internal input (delegatesFocus)`, async ({ page }) => {
+		await page.setContent(`<button>Before</button><kol-input-checkbox _label="Checkbox"></kol-input-checkbox><button>After</button>`);
+
+		const beforeButton = page.locator('button').first();
+		const input = page.locator('input');
+
+		// Focus on the "Before" button
+		await beforeButton.focus();
+		await page.waitForChanges();
+
+		// Press Tab to move to checkbox
+		await page.keyboard.press('Tab');
+		await page.waitForChanges();
+
+		// Verify the internal input has focus (delegatesFocus should make host focusable)
+		const isFocused = await input.evaluate((el) => el === document.activeElement || (el.getRootNode() as ShadowRoot | Document).activeElement === el);
+		expect(isFocused).toBe(true);
+	});
 });