fix: update focus methods across components for consistent behavior and improved focus management

deleonio · deleonio · commit f30d6d8784fe · 2026-03-24T10:13:36.000+01:00
diff --git a/packages/components/src/components/accordion/shadow.tsx b/packages/components/src/components/accordion/shadow.tsx
@@ -14,7 +14,6 @@ import type {
 } from '../../schema';
 import { featureHint, validateAccordionCallbacks, validateDisabled, validateLabel, validateOpen } from '../../schema';
 import { nonce } from '../../utils/dev.utils';
-import { propagateFocus } from '../../utils/element-focus';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import { watchHeadingLevel } from '../heading/validation';
 
@@ -53,8 +52,8 @@ export class KolAccordion implements AccordionAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.buttonWcRef);
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	private handleOnClick = (event: MouseEvent) => {
diff --git a/packages/components/src/components/badge/shadow.tsx b/packages/components/src/components/badge/shadow.tsx
@@ -56,7 +56,7 @@ export class KolBadge implements BadgeAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus(): Promise<void> {
-		return Promise.resolve(this.smartButtonRef?.focus());
+		return Promise.resolve(this.smartButtonRef?.focus(this.smartButtonRef as HTMLElement));
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/button-link/shadow.tsx b/packages/components/src/components/button-link/shadow.tsx
@@ -19,7 +19,6 @@ import type {
 	TooltipAlignPropType,
 	VariantClassNamePropType,
 } from '../../schema';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * The **ButtonLink** component is semantically a button but has the appearance of a link. All relevant properties of the Button component are adopted and extended with the design-defining properties of a link.
@@ -62,8 +61,8 @@ export class KolButtonLink implements ButtonLinkProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.buttonWcRef);
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/button/component.tsx b/packages/components/src/components/button/component.tsx
@@ -12,7 +12,6 @@ import type {
 	ButtonTypePropType,
 	CustomClassPropType,
 	DisabledPropType,
-	FocusableElement,
 	HideLabelPropType,
 	IconsPropType,
 	IdPropType,
@@ -68,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;
@@ -77,8 +76,8 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.buttonRef);
+	public async focus(host: HTMLElement): Promise<void> {
+		await propagateFocus(host, this.buttonRef);
 	}
 
 	private readonly hideTooltip = () => {
@@ -114,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);
 		}
 	};
 
@@ -316,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')
diff --git a/packages/components/src/components/button/shadow.tsx b/packages/components/src/components/button/shadow.tsx
@@ -19,7 +19,6 @@ import type {
 	SyncValueBySelectorPropType,
 	TooltipAlignPropType,
 } from '../../schema';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * The **Button** component is used to present users with action options and arrange them in a clear hierarchy. It helps users find the most important actions on a page or within a viewport and allows them to execute those actions. The button label clearly indicates which action will be triggered. Buttons allow users to confirm a change, complete steps in a task, or make decisions.
@@ -54,8 +53,8 @@ export class KolButton implements ButtonProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.buttonWcRef);
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/details/shadow.tsx b/packages/components/src/components/details/shadow.tsx
@@ -3,7 +3,6 @@ import KolCollapsibleFc, { type CollapsibleProps } from '../../functional-compon
 import type { DetailsAPI, DetailsCallbacksPropType, DetailsStates, DisabledPropType, FocusableElement, HeadingLevel, LabelPropType } from '../../schema';
 import { validateDetailsCallbacks, validateDisabled, validateLabel, validateOpen } from '../../schema';
 import { nonce } from '../../utils/dev.utils';
-import { propagateFocus } from '../../utils/element-focus';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import { watchHeadingLevel } from '../heading/validation';
 
@@ -39,8 +38,8 @@ export class KolDetails implements DetailsAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.buttonWcRef);
+	public async focus(): Promise<void> {
+		await this.buttonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	private toggleTimeout?: ReturnType<typeof setTimeout>;
diff --git a/packages/components/src/components/form/shadow.tsx b/packages/components/src/components/form/shadow.tsx
@@ -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 (
diff --git a/packages/components/src/components/link-button/shadow.tsx b/packages/components/src/components/link-button/shadow.tsx
@@ -19,7 +19,6 @@ import type {
 	ShortKeyPropType,
 	TooltipAlignPropType,
 } from '../../schema';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * The **LinkButton** component is semantically a link but has the appearance of a button. All relevant properties of the Link component are adopted and extended with the design-defining properties of a button.
@@ -45,8 +44,8 @@ export class KolLinkButton implements LinkButtonProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.linkWcRef);
+	public async focus(): Promise<void> {
+		await this.linkWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/link/component.tsx b/packages/components/src/components/link/component.tsx
@@ -12,7 +12,6 @@ import type {
 	CustomClassPropType,
 	DisabledPropType,
 	DownloadPropType,
-	FocusableElement,
 	HideLabelPropType,
 	HrefPropType,
 	InlinePropType,
@@ -70,7 +69,7 @@ import clsx from '../../utils/clsx';
 	tag: 'kol-link-wc',
 	shadow: false,
 })
-export class KolLinkWc implements InternalLinkAPI, FocusableElement {
+export class KolLinkWc implements InternalLinkAPI {
 	@Element() private readonly host?: HTMLKolLinkElement;
 
 	private anchorRef?: HTMLAnchorElement;
@@ -91,8 +90,8 @@ export class KolLinkWc implements InternalLinkAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.anchorRef);
+	public async focus(host: HTMLElement): Promise<void> {
+		await propagateFocus(host, this.anchorRef);
 	}
 
 	private readonly onClick = (event: Event) => {
diff --git a/packages/components/src/components/link/shadow.tsx b/packages/components/src/components/link/shadow.tsx
@@ -20,7 +20,6 @@ import type {
 	TooltipAlignPropType,
 	VariantClassNamePropType,
 } from '../../schema';
-import { propagateFocus } from '../../utils/element-focus';
 
 @Component({
 	tag: 'kol-link',
@@ -41,8 +40,8 @@ export class KolLink implements LinkProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.linkWcRef);
+	public async focus(): Promise<void> {
+		await this.linkWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/popover-button/component.tsx b/packages/components/src/components/popover-button/component.tsx
@@ -1,6 +1,6 @@
 import { autoUpdate } from '@floating-ui/dom';
 import type { JSX } from '@stencil/core';
-import { Component, h, Method, Prop, State, Watch } from '@stencil/core';
+import { Component, Element, h, Method, Prop, State, Watch } from '@stencil/core';
 import { KolButtonWcTag } from '../../core/component-names';
 import type {
 	AccessKeyPropType,
@@ -23,6 +23,7 @@ import { validateInline, validatePopoverAlign } from '../../schema';
 import type { PopoverButtonProps, PopoverButtonStates } from '../../schema/components/popover-button';
 import { alignFloatingElements } from '../../utils/align-floating-elements';
 import clsx from '../../utils/clsx';
+import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * @internal
@@ -34,6 +35,8 @@ import clsx from '../../utils/clsx';
 })
 // class implementing PopoverButtonProps and not API because we don't want to repeat the entire state and validation for button props
 export class KolPopoverButton implements PopoverButtonProps {
+	@Element() host!: HTMLElement;
+
 	private refButton?: HTMLKolButtonWcElement;
 	private refPopover?: HTMLDivElement;
 	private cleanupAutoPositioning?: () => void;
@@ -70,8 +73,8 @@ export class KolPopoverButton implements PopoverButtonProps {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.refButton?.focus());
+	public async focus(host: HTMLElement): Promise<void> {
+		await propagateFocus(host, this.refButton as HTMLElement);
 	}
 
 	/* Regarding type issue see https://github.com/microsoft/TypeScript/issues/54864 */
diff --git a/packages/components/src/components/popover-button/shadow.tsx b/packages/components/src/components/popover-button/shadow.tsx
@@ -17,7 +17,6 @@ import type {
 	TooltipAlignPropType,
 } from '../../schema';
 import type { PopoverButtonProps } from '../../schema/components/popover-button';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * @slot - The popover content.
@@ -59,8 +58,8 @@ export class KolPopoverButton implements PopoverButtonProps {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.ref);
+	public async focus(): Promise<void> {
+		await this.ref?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/select/component.tsx b/packages/components/src/components/select/component.tsx
@@ -4,7 +4,6 @@ import clsx from '../../utils/clsx';
 
 import type {
 	DisabledPropType,
-	FocusableElement,
 	HideLabelPropType,
 	HideMsgPropType,
 	HintPropType,
@@ -30,6 +29,7 @@ import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolSelectStateWrapperFc, { type SelectStateWrapperProps } from '../../functional-component-wrappers/SelectStateWrapper/SelectStateWrapper';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { SelectController } from './controller';
 
@@ -41,7 +41,7 @@ import { SelectController } from './controller';
 	tag: 'kol-select-wc',
 	shadow: false,
 })
-export class KolSelectWc implements SelectAPI, FocusableElement {
+export class KolSelectWc implements SelectAPI {
 	@Element() private readonly host?: HTMLKolSelectWcElement;
 	private selectRef?: HTMLSelectElement;
 
@@ -66,9 +66,8 @@ export class KolSelectWc implements SelectAPI, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await this.host?.componentOnReady();
-		return this.selectRef?.focus();
+	public async focus(host: HTMLElement): Promise<void> {
+		await propagateFocus(host, this.selectRef);
 	}
 
 	private getFormFieldProps(): FormFieldStateWrapperProps {
@@ -245,7 +244,7 @@ export class KolSelectWc implements SelectAPI, FocusableElement {
 	@State() private inputHasFocus = false;
 
 	public constructor() {
-		this.controller = new SelectController(this, 'select', this.host);
+		this.controller = new SelectController(this, 'select', this.host as HTMLElement);
 	}
 
 	private showAsAlert(): boolean {
diff --git a/packages/components/src/components/select/shadow.tsx b/packages/components/src/components/select/shadow.tsx
@@ -19,7 +19,6 @@ import type {
 } from '../../schema';
 
 import { KolSelectWcTag } from '../../core/component-names';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * @slot - The label of the input field.
@@ -51,8 +50,8 @@ export class KolSelect implements SelectProps, FocusableElement {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.selectWcRef);
+	public async focus(): Promise<void> {
+		await this.selectWcRef?.focus(this.host as HTMLElement);
 	}
 
 	public render(): JSX.Element {
diff --git a/packages/components/src/components/skip-nav/shadow.tsx b/packages/components/src/components/skip-nav/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 type { LabelPropType, LinkProps, SkipNavAPI, SkipNavStates, Stringified } from '../../schema';
 import { validateLabel } from '../../schema';
 
@@ -19,6 +19,7 @@ import { KolLinkWcTag } from '../../core/component-names';
 	shadow: true,
 })
 export class KolSkipNav implements SkipNavAPI {
+	@Element() private readonly host?: HTMLKolSkipNavElement;
 	private firstLinkRef?: HTMLKolLinkWcElement;
 
 	public render(): JSX.Element {
@@ -41,8 +42,8 @@ export class KolSkipNav implements SkipNavAPI {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		return Promise.resolve(this.firstLinkRef?.focus());
+	public async focus(): Promise<void> {
+		await this.firstLinkRef?.focus(this.host as HTMLElement);
 	}
 
 	/**
diff --git a/packages/components/src/components/split-button/shadow.tsx b/packages/components/src/components/split-button/shadow.tsx
@@ -21,7 +21,6 @@ import type {
 import { KolButtonWcTag, KolPopoverWcTag } from '../../core/component-names';
 import { translate } from '../../i18n';
 import clsx from '../../utils/clsx';
-import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * The **SplitButton** component can be used to display a two-part button. The primary button is typically used for
@@ -57,8 +56,8 @@ export class KolSplitButton implements SplitButtonProps /*, SplitButtonAPI*/ {
 	 * Sets focus on the internal element.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.primaryButtonWcRef);
+	public async focus(): Promise<void> {
+		await this.primaryButtonWcRef?.focus(this.host as HTMLElement);
 	}
 
 	private readonly clickButtonHandler = {
diff --git a/packages/components/src/components/tabs/shadow.tsx b/packages/components/src/components/tabs/shadow.tsx
@@ -32,7 +32,6 @@ import { KeyboardKey } from '../../schema/enums';
 import type { HasCreateButtonPropType } from '../../schema/props/has-create-button';
 import { validateHasCreateButton } from '../../schema/props/has-create-button';
 import clsx from '../../utils/clsx';
-import { propagateFocus } from '../../utils/element-focus';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
 // https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-2/tabs.html
 
@@ -162,8 +161,8 @@ export class KolTabs implements TabsAPI, FocusableElement {
 	 * Sets focus on the current tab button.
 	 */
 	@Method()
-	public async focus() {
-		await propagateFocus(this.host, this.currentTabButtonRef);
+	public async focus(): Promise<void> {
+		await this.currentTabButtonRef?.focus(this.host as HTMLElement);
 	}
 
 	private readonly catchTabButtonRef = (ref?: HTMLKolButtonWcElement) => {
diff --git a/packages/components/src/components/toolbar/shadow.tsx b/packages/components/src/components/toolbar/shadow.tsx
diff --git a/packages/components/src/components/tree-item/component.tsx b/packages/components/src/components/tree-item/component.tsx
diff --git a/packages/components/src/functional-components/Button/tests/snapshot.test.tsx b/packages/components/src/functional-components/Button/tests/snapshot.test.tsx
diff --git a/packages/components/src/utils/element-focus.ts b/packages/components/src/utils/element-focus.ts
diff --git a/packages/samples/react/src/scenarios/focus-elements.tsx b/packages/samples/react/src/scenarios/focus-elements.tsx
diff --git a/packages/tools/visual-tests/tests/sample-app.routes.js b/packages/tools/visual-tests/tests/sample-app.routes.js

Original file line number	Diff line number	Diff line change
`@@ -56,7 +56,7 @@ export class KolBadge implements BadgeAPI, FocusableElement {`
`56`	`56`	`*/`
`57`	`57`	`@Method()`
`58`	`58`	`public async focus(): Promise<void> {`
`59`		`- return Promise.resolve(this.smartButtonRef?.focus());`
	`59`	`+ return Promise.resolve(this.smartButtonRef?.focus(this.smartButtonRef as HTMLElement));`
`60`	`60`	`}`
`61`	`61`
`62`	`62`	`public render(): JSX.Element {`