refactor: replace KolPopover with PopoverFC in components

- Updated the KolPopoverButton and KolSplitButton components to use the new PopoverFC functional component.
- Removed the legacy KolPopover component and its associated tests.
- Introduced PopoverController and popoverPropsConfig for managing popover state and props.
- Added align and show props for the new PopoverFC to control visibility and positioning.
- Updated documentation to reflect changes in naming conventions and component architecture.

Author: deleonio

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

@@ -72,9 +72,22 @@ This modular layout is the backbone for the architectural patterns described in
 - **Stencil** is used for authoring web components with **shadow: true** only (Shadow DOM enabled for style isolation).
 - Components without Shadow DOM (`shadow: false`) are implemented as **Functional Components** instead of web components to avoid style conflicts and reduce maintainability burden.
 - Components must compile to framework-agnostic Custom Elements.
-- Public API properties use an underscored naming convention (e.g. `_name`) to separate external inputs from internal state.
+- **Public API properties (Web Component Props/Attributes) use an underscored naming convention** (e.g. `_name`) to separate external inputs from internal state. This convention applies **only at the Web Component boundary** (Props in `@Prop()` decorators). Internally, controller state, render props, and functional component parameters do **not** use underscore prefixes — they use clear, self-describing names (`visible`, `count`, `label`). The underscore signals "this is a managed property exposed to HTML consumers," not "this is internal."
 - Documentation and code follow the `KoliBri` casing and repository conventions.
 
+### Naming Conventions Across Layers
+
+The underscore naming convention is **scoped to the Web Component public API boundary**. Here's how naming changes across layers:
+
+| Layer                                   | Example                             | Purpose                                                            |
+| --------------------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
+| **Web Component (Public API)**          | `_name`, `_visible`, `_label`       | Signals managed properties exposed to HTML consumers via `@Prop()` |
+| **Controller (Internal State)**         | `name`, `visible`, `label`, `count` | Clear, self-describing state names — no underscore prefix needed   |
+| **Functional Component (Render Props)** | `visible`, `align`, `count`         | Parameters passed from controller — no underscore prefix           |
+| **Schema Helpers**                      | `nameProp`, `visibleProp`           | Prop definitions for validation and normalization                  |
+
+**Rule of thumb**: Use underscore (`_`) **only** where consumers interact with the component via HTML (Web Component `@Prop()` decorators). Everywhere else — controllers, state, derived values, render props — use natural, descriptive names.
+
 ## 3. Context and Scope
 
 The skeleton lives inside `packages/components` and does not depend on runtime frameworks. External consumers interact through HTML attributes or DOM APIs.
@@ -85,7 +98,7 @@ The skeleton lives inside `packages/components` and does not depend on runtime f
 - **Encapsulation**: Components maintain consistent appearance regardless of host environment
 - **Maintainability**: Clear boundaries prevent unintended style interactions
 
-Components that historically did not use Shadow DOM (`shadow: false`) are being migrated to **Functional Components** instead, which can be composed into other components without Shadow DOM overhead while maintaining clean architectural separation.
+**Shadow DOM is mandatory for all KoliBri Web Components.** Components with `shadow: false` (historically suffixed `-wc`) are considered legacy and will be fully replaced and removed. The migration target is the Skeleton Pattern: each such component is rewritten as a proper Shadow DOM Web Component paired with a Functional Component for internal composition. No new `shadow: false` components will be introduced. The `-wc` variants are not a supported architecture going forward.
 
 ```mermaid
 flowchart LR

packages/components/src/components/_skeleton/TODO_PROP_ENFORCEMENT.md

@@ -6,16 +6,16 @@ Wenn Props über `PropsConfigShape` + `ApiFromConfig` in `api.tsx` definiert wer
 
 Das **Prop-Dreieck** besteht aus drei Teilen — nur einer davon ist type-erzwungen:
 
-| Teil | Type-erzwungen? | Was passiert bei Fehlen |
-|------|----------------|------------------------|
-| Felddeklaration `_name!: string` | **Ja** — via `ComponentProps<T>` in `WebComponentInterface` | compile error |
-| `@Prop()` Decorator | **Nein** | kein Attribut-Binding, silent runtime bug |
-| `@Watch('_name')` Decorator | **Nein** (`watchName()` Methode wird erzwungen, aber nicht der Decorator) | Stencil ruft Methode nie auf, silent runtime bug |
-| Forwarding in `componentWillLoad()` | **Nein** | Prop-Wert kommt nie im Controller an |
+| Teil                                | Type-erzwungen?                                                           | Was passiert bei Fehlen                          |
+| ----------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------ |
+| Felddeklaration `_name!: string`    | **Ja** — via `ComponentProps<T>` in `WebComponentInterface`               | compile error                                    |
+| `@Prop()` Decorator                 | **Nein**                                                                  | kein Attribut-Binding, silent runtime bug        |
+| `@Watch('_name')` Decorator         | **Nein** (`watchName()` Methode wird erzwungen, aber nicht der Decorator) | Stencil ruft Methode nie auf, silent runtime bug |
+| Forwarding in `componentWillLoad()` | **Nein**                                                                  | Prop-Wert kommt nie im Controller an             |
 
 ## Aktueller Stand
 
-`implements WebComponentInterface<SkeletonApi>` ist korrekt und schon vorhanden — es deckt alles ab, was TypeScript abdecken *kann*. Die Lücke ist Stencil-spezifisch: Stencil-Decorators sind reine Metadaten und für das TypeScript-Typsystem unsichtbar.
+`implements WebComponentInterface<SkeletonApi>` ist korrekt und schon vorhanden — es deckt alles ab, was TypeScript abdecken _kann_. Die Lücke ist Stencil-spezifisch: Stencil-Decorators sind reine Metadaten und für das TypeScript-Typsystem unsichtbar.
 
 ## Lösungsoptionen
 

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

@@ -36,7 +36,6 @@ 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 { KolProgress } from './progress/component';
 import { KolQuote } from './quote/component';
 import { KolSelect } from './select/shadow';
@@ -93,7 +92,6 @@ export const COMPONENTS = [
 	KolModal,
 	KolNav,
 	KolPagination,
-	KolPopover,
 	KolProgress,
 	KolPopoverButton,
 	KolQuote,

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

@@ -1,7 +1,7 @@
-import { autoUpdate } from '@floating-ui/dom';
 import type { JSX } from '@stencil/core';
 import { Component, h, Method, Prop, State, Watch } from '@stencil/core';
 import { KolButtonWcTag } from '../../core/component-names';
+import { PopoverFC } from '../../internal/functional-components/popover/component';
 import type {
 	AccessKeyPropType,
 	AriaDescriptionPropType,
@@ -21,7 +21,6 @@ import type {
 } from '../../schema';
 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';
 
 /**
@@ -36,7 +35,8 @@ import clsx from '../../utils/clsx';
 export class KolPopoverButton implements PopoverButtonProps {
 	private refButton?: HTMLKolButtonWcElement;
 	private refPopover?: HTMLDivElement;
-	private cleanupAutoPositioning?: () => void;
+	private handleToggleBound = this.handleToggle.bind(this);
+	private handleBeforeToggleBound = this.handleBeforeToggle.bind(this);
 	private on: ButtonCallbacksPropType<StencilUnknown> = {
 		onClick: this.handleButtonClick.bind(this),
 	};
@@ -83,39 +83,11 @@ export class KolPopoverButton implements PopoverButtonProps {
 				// Reset the flag after the event loop tick.
 				this.justClosed = false;
 			}, 10); // timeout of 0 should be sufficient but doesn't work in Safari Mobile (needs further investigation).
-		} else {
-			if (this.refPopover) {
-				/**
-				 * Avoid "flicker" by hiding the element until the position is set in the `toggle` event handler. `alignFloatingElements` is responsible for setting the visibility back to 'visible'.
-				 */
-				this.refPopover.style.visibility = 'hidden';
-			}
-		}
-	}
-
-	private alignPopover() {
-		if (this.refPopover && this.refButton) {
-			void alignFloatingElements({
-				align: this.state._popoverAlign,
-				floatingElement: this.refPopover,
-				referenceElement: this.refButton,
-			});
 		}
 	}
 
 	private handleToggle(event: Event) {
 		this.popoverOpen = (event as ToggleEvent).newState === 'open';
-
-		if (this.popoverOpen) {
-			if (this.refPopover && this.refButton) {
-				this.cleanupAutoPositioning = autoUpdate(this.refButton, this.refPopover, () => {
-					this.alignPopover();
-				});
-			}
-		} else if (this.cleanupAutoPositioning) {
-			this.cleanupAutoPositioning();
-			this.cleanupAutoPositioning = undefined;
-		}
 	}
 
 	private handleButtonClick() {
@@ -125,15 +97,22 @@ export class KolPopoverButton implements PopoverButtonProps {
 		}
 	}
 
+	private handleEscape = (event: KeyboardEvent) => {
+		if (event.key === 'Escape') {
+			this.refPopover?.hidePopover();
+		}
+	};
+
 	public componentDidRender() {
-		this.refPopover?.addEventListener('toggle', this.handleToggle.bind(this));
-		this.refPopover?.addEventListener('beforetoggle', this.handleBeforeToggle.bind(this));
+		this.refPopover?.addEventListener('toggle', this.handleToggleBound);
+		this.refPopover?.addEventListener('beforetoggle', this.handleBeforeToggleBound);
+		this.refPopover?.addEventListener('keydown', this.handleEscape);
 	}
 
 	public disconnectedCallback() {
-		this.refPopover?.removeEventListener('toggle', this.handleToggle.bind(this));
-		this.refPopover?.removeEventListener('beforetoggle', this.handleBeforeToggle.bind(this));
-		this.cleanupAutoPositioning?.();
+		this.refPopover?.removeEventListener('toggle', this.handleToggleBound);
+		this.refPopover?.removeEventListener('beforetoggle', this.handleBeforeToggleBound);
+		this.refPopover?.removeEventListener('keydown', this.handleEscape);
 	}
 
 	public render(): JSX.Element {
@@ -174,9 +153,18 @@ export class KolPopoverButton implements PopoverButtonProps {
 					<slot name="expert" slot="expert"></slot>
 				</KolButtonWcTag>
 
-				<div ref={(element) => (this.refPopover = element)} data-testid="popover-content" popover="auto" id="popover" class="kol-popover-button__popover">
+				<PopoverFC
+					align={this.state._popoverAlign || 'bottom'}
+					show={this.popoverOpen}
+					visible={this.popoverOpen}
+					refPopoverElement={(el) => (this.refPopover = el)}
+					refArrowElement={() => {}}
+					data-testid="popover-content"
+					id="popover"
+					class="kol-popover-button__popover"
+				>
 					<slot />
-				</div>
+				</PopoverFC>
 			</div>
 		);
 	}