fix: reintroduce propagateFocus import in multiple components for consistent focus management

deleonio · deleonio · commit 9cbe195311bc · 2026-03-24T07:10:03.000+01:00
diff --git a/packages/components/src/components/accordion/shadow.tsx b/packages/components/src/components/accordion/shadow.tsx
@@ -2,7 +2,6 @@
 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,
@@ -15,6 +14,7 @@ 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';
 
diff --git a/packages/components/src/components/button-link/shadow.tsx b/packages/components/src/components/button-link/shadow.tsx
@@ -1,7 +1,6 @@
 import type { JSX } 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,
@@ -20,6 +19,7 @@ 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.
diff --git a/packages/components/src/components/button/component.tsx b/packages/components/src/components/button/component.tsx
@@ -56,8 +56,8 @@ 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 { dispatchDomEvent, KolEvent } from '../../utils/events';
 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';
 
diff --git a/packages/components/src/components/button/shadow.tsx b/packages/components/src/components/button/shadow.tsx
@@ -1,7 +1,6 @@
 import type { JSX } 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,
@@ -20,6 +19,7 @@ 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.
diff --git a/packages/components/src/components/details/shadow.tsx b/packages/components/src/components/details/shadow.tsx
@@ -1,9 +1,9 @@
 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 { propagateFocus } from '../../utils/element-focus';
 import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import { watchHeadingLevel } from '../heading/validation';
 
diff --git a/packages/components/src/components/input-checkbox/shadow.tsx b/packages/components/src/components/input-checkbox/shadow.tsx
@@ -26,8 +26,8 @@ import type {
 	TooltipAlignPropType,
 } from '../../schema';
 
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { InputCheckboxController } from './controller';
 
 import KolCheckboxStateWrapperFc, { type CheckboxStateWrapperProps } from '../../functional-component-wrappers/CheckboxStateWrapper/CheckboxStateWrapper';
diff --git a/packages/components/src/components/input-date/shadow.tsx b/packages/components/src/components/input-date/shadow.tsx
@@ -33,8 +33,8 @@ 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 { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputDateController } from './controller';
 
diff --git a/packages/components/src/components/input-email/shadow.tsx b/packages/components/src/components/input-email/shadow.tsx
@@ -33,8 +33,8 @@ import type {
 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 { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputEmailController } from './controller';
 
diff --git a/packages/components/src/components/input-file/shadow.tsx b/packages/components/src/components/input-file/shadow.tsx
@@ -30,8 +30,8 @@ import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../functional-component-wrappers/InputStateWrapper/InputStateWrapper';
 import { translate } from '../../i18n';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { InputFileController } from './controller';
 
 /**
diff --git a/packages/components/src/components/input-number/shadow.tsx b/packages/components/src/components/input-number/shadow.tsx
@@ -32,8 +32,8 @@ import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../functional-component-wrappers/InputStateWrapper/InputStateWrapper';
 import { IconFC } from '../../internal/functional-components/icon/component';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputNumberController } from './controller';
 
diff --git a/packages/components/src/components/input-password/shadow.tsx b/packages/components/src/components/input-password/shadow.tsx
@@ -35,8 +35,8 @@ import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../funct
 import KolIconButtonFc from '../../functional-components/IconButton';
 import { translate } from '../../i18n';
 import type { PasswordVariantPropType } from '../../schema/props/variant/password-variant';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputPasswordController } from './controller';
 
diff --git a/packages/components/src/components/input-radio/shadow.tsx b/packages/components/src/components/input-radio/shadow.tsx
@@ -23,8 +23,8 @@ import type {
 	TooltipAlignPropType,
 } from '../../schema';
 
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputRadioController } from './controller';
 
diff --git a/packages/components/src/components/input-range/shadow.tsx b/packages/components/src/components/input-range/shadow.tsx
@@ -28,8 +28,8 @@ import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../
 import KolInputContainerFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolInputStateWrapperFc, { type InputStateWrapperProps } from '../../functional-component-wrappers/InputStateWrapper/InputStateWrapper';
 import KolSuggestionsFc from '../../functional-components/Suggestions';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputRangeController } from './controller';
 
diff --git a/packages/components/src/components/input-text/shadow.tsx b/packages/components/src/components/input-text/shadow.tsx
@@ -35,8 +35,8 @@ import type {
 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 { propagateFocus } from '../../utils/element-focus';
 import { propagateSubmitEventToForm } from '../form/controller';
 import { InputTextController } from './controller';
 
diff --git a/packages/components/src/components/link-button/shadow.tsx b/packages/components/src/components/link-button/shadow.tsx
@@ -1,7 +1,6 @@
 import type { JSX } from '@stencil/core';
 import { Component, Element, h, Method, Prop } from '@stencil/core';
 import { KolLinkWcTag } from '../../core/component-names';
-import { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccessKeyPropType,
 	AlternativeButtonLinkRolePropType,
@@ -20,6 +19,7 @@ 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.
diff --git a/packages/components/src/components/link/component.tsx b/packages/components/src/components/link/component.tsx
@@ -53,8 +53,8 @@ import {
 	validateVariantClassName,
 } from '../../schema';
 import { validateTabIndex } from '../../schema/props/tab-index';
-import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import { propagateFocus } from '../../utils/element-focus';
+import { dispatchDomEvent, KolEvent } from '../../utils/events';
 import type { UnsubscribeFunction } from './ariaCurrentService';
 import { onLocationChange } from './ariaCurrentService';
 
diff --git a/packages/components/src/components/link/shadow.tsx b/packages/components/src/components/link/shadow.tsx
@@ -1,7 +1,6 @@
 import type { JSX } from '@stencil/core';
 import { Component, Element, h, Method, Prop } from '@stencil/core';
 import { KolLinkWcTag } from '../../core/component-names';
-import { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccessKeyPropType,
 	AlternativeButtonLinkRolePropType,
@@ -21,6 +20,7 @@ import type {
 	TooltipAlignPropType,
 	VariantClassNamePropType,
 } from '../../schema';
+import { propagateFocus } from '../../utils/element-focus';
 
 @Component({
 	tag: 'kol-link',
diff --git a/packages/components/src/components/popover-button/shadow.tsx b/packages/components/src/components/popover-button/shadow.tsx
@@ -1,7 +1,6 @@
 import type { JSX } from '@stencil/core';
 import { Component, Element, h, Method, Prop } from '@stencil/core';
 import { KolPopoverButtonWcTag } from '../../core/component-names';
-import { propagateFocus } from '../../utils/element-focus';
 import type {
 	AccessKeyPropType,
 	AriaDescriptionPropType,
@@ -18,6 +17,7 @@ import type {
 	TooltipAlignPropType,
 } from '../../schema';
 import type { PopoverButtonProps } from '../../schema/components/popover-button';
+import { propagateFocus } from '../../utils/element-focus';
 
 /**
  * @slot - The popover content.
diff --git a/packages/components/src/components/single-select/shadow.tsx b/packages/components/src/components/single-select/shadow.tsx
@@ -37,8 +37,8 @@ import { translate } from '../../i18n';
 import { IconFC } from '../../internal/functional-components/icon/component';
 import type { EventDetail } from '../../schema/interfaces/EventDetail';
 import clsx from '../../utils/clsx';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { SingleSelectController } from './controller';
 
 /**
diff --git a/packages/components/src/components/tabs/shadow.tsx b/packages/components/src/components/tabs/shadow.tsx
@@ -1,8 +1,9 @@
 import type { JSX } from '@stencil/core';
-import { Component, Element, h, Prop, State, Watch } from '@stencil/core';
+import { Component, Element, h, Method, Prop, State, Watch } from '@stencil/core';
 import type {
 	AlignPropType,
 	ButtonCallbacksPropType,
+	FocusableElement,
 	KoliBriTabsCallbacks,
 	LabelPropType,
 	StencilUnknown,
@@ -31,6 +32,7 @@ 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
 
@@ -44,11 +46,12 @@ import { dispatchDomEvent, KolEvent } from '../../utils/events';
 	},
 	shadow: true,
 })
-export class KolTabs implements TabsAPI {
+export class KolTabs implements TabsAPI, FocusableElement {
 	@Element() private readonly host?: HTMLKolTabsElement;
 	private tabPanelsElement?: HTMLElement;
 	private onCreateLabel = `${translate('kol-new')} …`;
 	private currentFocusIndex: number | undefined;
+	private currentTabButtonRef?: HTMLKolButtonWcElement;
 
 	private nextPossibleTabIndex = (tabs: TabButtonProps[], offset: number, step = 1): number => {
 		const nextOffset = offset + step;
@@ -155,13 +158,28 @@ export class KolTabs implements TabsAPI {
 		onMouseDown: this.onMouseDown,
 	};
 
+	/**
+	 * Sets focus on the current tab button.
+	 */
+	@Method()
+	public async focus() {
+		await propagateFocus(this.host, this.currentTabButtonRef);
+	}
+
+	private readonly catchTabButtonRef = (ref?: HTMLKolButtonWcElement) => {
+		if (ref) {
+			this.currentTabButtonRef = ref;
+		}
+	};
+
 	private renderButtonGroup() {
 		return (
 			// Rule is disabled, because KolButtonWc is focusable.
 			// eslint-disable-next-line jsx-a11y/interactive-supports-focus
 			<div aria-label={this.state._label} class="kol-tabs__button-group" role="tablist" onKeyDown={this.onKeyDown} onBlur={this.onBlur}>
 				{this.state._tabs.map((button: TabButtonProps, index: number) => (
 					<KolButtonWcTag
+						ref={this.state._selected === index ? this.catchTabButtonRef : undefined}
 						_disabled={button._disabled}
 						_icons={button._icons}
 						_hideLabel={button._hideLabel}
diff --git a/packages/components/src/components/textarea/shadow.tsx b/packages/components/src/components/textarea/shadow.tsx
@@ -33,8 +33,8 @@ import type {
 import KolFormFieldStateWrapperFc, { type FormFieldStateWrapperProps } from '../../functional-component-wrappers/FormFieldStateWrapper/FormFieldStateWrapper';
 import KolInputContainerStateWrapperFc from '../../functional-component-wrappers/InputContainerStateWrapper/InputContainerStateWrapper';
 import KolTextAreaStateWrapperFc, { type TextAreaStateWrapperProps } from '../../functional-component-wrappers/TextAreaStateWrapper/TextAreaStateWrapper';
-import { propagateFocus } from '../../utils/element-focus';
 import { nonce } from '../../utils/dev.utils';
+import { propagateFocus } from '../../utils/element-focus';
 import { TextareaController } from './controller';
 
 /**
diff --git a/packages/components/src/components/toolbar/shadow.tsx b/packages/components/src/components/toolbar/shadow.tsx
@@ -1,12 +1,13 @@
 import type { JSX } from '@stencil/core';
-import { Component, Element, h, Listen, Prop, State, Watch } from '@stencil/core';
+import { Component, Element, h, Listen, Method, Prop, State, Watch } from '@stencil/core';
 
 import { KolButtonWcTag, KolLinkWcTag } from '../../core/component-names';
-import type { LabelPropType, ToolbarAPI, ToolbarItemPropType, ToolbarItemsPropType, ToolbarStates } from '../../schema';
+import type { FocusableElement, LabelPropType, ToolbarAPI, ToolbarItemPropType, ToolbarItemsPropType, ToolbarStates } from '../../schema';
 import { validateLabel, validateToolbarItems } from '../../schema';
 import { KeyboardKey } from '../../schema/enums';
 import type { OrientationPropType } from '../../schema/props/orientation';
 import { validateOrientation } from '../../schema/props/orientation';
+import { propagateFocus } from '../../utils/element-focus';
 
 @Component({
 	tag: 'kol-toolbar',
@@ -15,7 +16,7 @@ import { validateOrientation } from '../../schema/props/orientation';
 	},
 	shadow: true,
 })
-export class KolToolbar implements ToolbarAPI {
+export class KolToolbar implements ToolbarAPI, FocusableElement {
 	@Element() host!: HTMLElement;
 
 	@State() public state: ToolbarStates = {
@@ -26,10 +27,19 @@ export class KolToolbar implements ToolbarAPI {
 	@State() private currentIndex: number = 0;
 
 	private indexToElement = new Map<number, HTMLKolLinkWcElement | HTMLKolButtonWcElement>();
+	private currentCatchRefIndex?: number;
+
 	private normalizeItem(item: ToolbarItemPropType): ToolbarItemPropType {
 		const { _icons, _disabled, ...rest } = item;
 		return { ...rest, _icons, _disabled };
 	}
+
+	private readonly catchToolbarItemRef = (el?: HTMLKolLinkWcElement | HTMLKolButtonWcElement) => {
+		if (this.currentCatchRefIndex !== undefined && el) {
+			this.indexToElement.set(this.currentCatchRefIndex, el);
+		}
+	};
+
 	private renderItem = (raw: ToolbarItemPropType, index: number): JSX.Element => {
 		const element = this.normalizeItem(raw);
 		const tabIndex = index === this.currentIndex && !element?._disabled ? 0 : -1;
@@ -40,13 +50,11 @@ export class KolToolbar implements ToolbarAPI {
 			_tabIndex: tabIndex,
 			_variant: 'normal',
 		};
-		const catchRef = (el?: HTMLKolLinkWcElement | HTMLKolButtonWcElement) => {
-			if (el) this.indexToElement.set(index, el);
-		};
+		this.currentCatchRefIndex = index;
 		return element.type === 'link' ? (
-			<KolLinkWcTag {...props} {...element} ref={catchRef}></KolLinkWcTag>
+			<KolLinkWcTag {...props} {...element} ref={this.catchToolbarItemRef}></KolLinkWcTag>
 		) : (
-			<KolButtonWcTag {...props} {...element} ref={catchRef}></KolButtonWcTag>
+			<KolButtonWcTag {...props} {...element} ref={this.catchToolbarItemRef}></KolButtonWcTag>
 		);
 	};
 
@@ -151,4 +159,13 @@ export class KolToolbar implements ToolbarAPI {
 		this.validateOrientation(this._orientation);
 		this.setFirstEnabledItemIndex();
 	}
+
+	/**
+	 * Sets focus on the first enabled toolbar item.
+	 */
+	@Method()
+	public async focus() {
+		const firstItem = this.getCurrentToolbarItem(this.currentIndex);
+		await propagateFocus(this.host, firstItem);
+	}
 }
diff --git a/packages/components/src/components/tree/shadow.tsx b/packages/components/src/components/tree/shadow.tsx
diff --git a/packages/samples/react/src/scenarios/focus-elements.tsx b/packages/samples/react/src/scenarios/focus-elements.tsx
