fix: propagate focus reliably across components to prevent layout issues

Author: deleonio

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

@@ -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/accordion/shadow.tsx

@@ -2,6 +2,7 @@
 import type { JSX } from '@stencil/core';
 import { Component, Element, h, Method, Prop, State, Watch } from '@stencil/core';
 import KolCollapsibleFc, { type CollapsibleProps } from '../../functional-components/Collapsible';
+import { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccordionAPI,
 	AccordionCallbacksPropType,
@@ -53,7 +54,7 @@ export class KolAccordion implements AccordionAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+		await propagateFocus(this.host, this.buttonWcRef);
 	}
 
 	private handleOnClick = (event: MouseEvent) => {

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

@@ -1,6 +1,7 @@
 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 { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccessKeyPropType,
 	AlternativeButtonLinkRolePropType,
@@ -41,6 +42,7 @@ import type {
 	shadow: true,
 })
 export class KolButtonLink implements ButtonLinkProps, FocusableElement {
+	@Element() private readonly host?: HTMLKolButtonLinkElement;
 	private buttonWcRef?: HTMLKolButtonWcElement;
 
 	private readonly catchRef = (ref?: HTMLKolButtonWcElement) => {
@@ -61,7 +63,7 @@ export class KolButtonLink implements ButtonLinkProps, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+		await propagateFocus(this.host, this.buttonWcRef);
 	}
 
 	public render(): JSX.Element {

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

@@ -57,6 +57,7 @@ import type { AriaHasPopupPropType } from '../../schema/props/aria-has-popup';
 import { validateAccessAndShortKey } from '../../schema/validators/access-and-short-key';
 import clsx from '../../utils/clsx';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateResetEventToForm, propagateSubmitEventToForm } from '../form/controller';
 import { AssociatedInputController } from '../input-adapter-leanup/associated.controller';
 
@@ -77,12 +78,7 @@ export class KolButtonWc implements ButtonAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.buttonRef?.focus();
-				resolve();
-			});
-		});
+		await propagateFocus(this.host, this.buttonRef);
 	}
 
 	private readonly hideTooltip = () => {

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

@@ -1,6 +1,7 @@
 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 { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccessKeyPropType,
 	AlternativeButtonLinkRolePropType,
@@ -33,6 +34,7 @@ import type {
 	shadow: true,
 })
 export class KolButton implements ButtonProps, FocusableElement {
+	@Element() private readonly host?: HTMLKolButtonElement;
 	private buttonWcRef?: HTMLKolButtonWcElement;
 
 	private readonly catchRef = (ref?: HTMLKolButtonWcElement) => {
@@ -53,7 +55,7 @@ export class KolButton implements ButtonProps, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+		await propagateFocus(this.host, this.buttonWcRef);
 	}
 
 	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 { 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/details/shadow.tsx

@@ -1,6 +1,7 @@
 import { Component, Element, h, type JSX, Method, Prop, State, Watch } from '@stencil/core';
 import KolCollapsibleFc, { type CollapsibleProps } from '../../functional-components/Collapsible';
 import type { DetailsAPI, DetailsCallbacksPropType, DetailsStates, DisabledPropType, FocusableElement, HeadingLevel, LabelPropType } from '../../schema';
+import { propagateFocus } from '../../utils/element-focus';
 import { validateDetailsCallbacks, validateDisabled, validateLabel, validateOpen } from '../../schema';
 import { nonce } from '../../utils/dev.utils';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
@@ -39,7 +40,7 @@ export class KolDetails implements DetailsAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return Promise.resolve(this.buttonWcRef?.focus());
+		await propagateFocus(this.host, this.buttonWcRef);
 	}
 
 	private toggleTimeout?: ReturnType<typeof setTimeout>;

packages/components/src/components/input-checkbox/shadow.tsx

@@ -26,6 +26,7 @@ import type {
 	TooltipAlignPropType,
 } from '../../schema';
 
+import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
 import { InputCheckboxController } from './controller';
 
@@ -75,12 +76,7 @@ export class KolInputCheckbox implements InputCheckboxAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.inputRef?.focus();
-				resolve();
-			});
-		});
+		await propagateFocus(this.host, this.inputRef);
 	}
 
 	private getFormFieldProps(): FormFieldStateWrapperProps {

packages/components/src/components/input-color/shadow.tsx

@@ -26,6 +26,7 @@ import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../functional-component-wrappers/InputStateWrapper/InputStateWrapper';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { InputColorController } from './controller';
 
 /**
@@ -96,12 +97,7 @@ export class KolInputColor implements InputColorAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.refInputText?.focus();
-				resolve();
-			});
-		});
+		await propagateFocus(this.host, this.refInputText);
 	}
 
 	private get hasSuggestions(): boolean {

packages/components/src/components/input-date/shadow.tsx

@@ -33,6 +33,7 @@ import { deprecatedHint } from '../../schema';
 import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../../functional-component-wrappers/FormFieldStateWrapper/FormFieldStateWrapper';
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../functional-component-wrappers/InputStateWrapper/InputStateWrapper';
+import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputDateController } from './controller';
@@ -73,12 +74,7 @@ export class KolInputDate implements InputDateAPI, FocusableElement {
 	 */
 	@Method()
 	public async focus() {
-		return new Promise<void>((resolve) => {
-			requestAnimationFrame(() => {
-				this.inputRef?.focus();
-				resolve();
-			});
-		});
+		await propagateFocus(this.host, this.inputRef);
 	}
 
 	/**