@octanejs/base-ui 0.1.49 → 0.1.51

package/src/popover.ts

@@ -1,1282 +0,0 @@
-// Ported from .base-ui/packages/react/src/popover/ (v1.6.0): store (PopoverStore/PopoverHandle),
-// root (context/PopoverRoot/PopoverInteractions), trigger, and the anchored open path
-// (Portal/Positioner/Popup/Arrow/Backdrop/Title/Description/Close), reusing the Store + floating
-// stack from Dialog. octane adaptations: forwardRef → ref-as-prop; native events; every Store
-// hook-method + hook threads an explicit slot; `React.createContext` → octane `createContext`;
-// `ReactDOM.flushSync` → octane `flushSync`.
-//
-// `openOnHover` is fully wired: the trigger side runs `useHoverReferenceInteraction` (+ safePolygon)
-// and the popup side runs `useHoverFloatingInteraction`.
-import {
-	createContext,
-	createElement,
-	Fragment,
-	useContext,
-	useMemo,
-	useRef,
-	useEffect,
-	useLayoutEffect,
-	useCallback,
-	useImperativeHandle,
-	isChildrenBlock,
-	flushSync,
-} from 'octane';
-
-import { S, subSlot } from './internal';
-import { useRenderElement } from './utils/useRenderElement';
-import { mergeProps } from './utils/mergeProps';
-import { useButton } from './utils/useButton';
-import { useBaseUiId } from './utils/useBaseUiId';
-import { createChangeEventDetails, REASONS } from './utils/createChangeEventDetails';
-import { EMPTY_OBJECT } from './utils/empty';
-import { ReactStore } from './utils/store/ReactStore';
-import { createSelector } from './utils/store/createSelector';
-import { Timeout } from './utils/useTimeout';
-import { useClick } from './utils/floating/useClick';
-import { useDismiss } from './utils/floating/useDismiss';
-import { FocusGuard } from './utils/floating/FocusGuard';
-import {
-	FloatingTree,
-	FloatingNode,
-	useFloatingParentNodeId,
-	useFloatingNodeId,
-} from './utils/floating/FloatingTree';
-import { FloatingFocusManager } from './utils/floating/FloatingFocusManager';
-import { FloatingPortal } from './utils/floating/FloatingPortal';
-import { useHoverFloatingInteraction } from './utils/floating/useHoverFloatingInteraction';
-import {
-	useAnchorPositioning,
-	type Side,
-	type Align,
-	type UseAnchorPositioningSharedParameters,
-} from './utils/useAnchorPositioning';
-import { usePositioner } from './utils/usePositioner';
-import { usePopupViewport } from './utils/usePopupViewport';
-import { useAnchoredPopupScrollLock } from './utils/useAnchoredPopupScrollLock';
-import { adaptiveOrigin } from './utils/adaptiveOriginMiddleware';
-import { InternalBackdrop } from './utils/InternalBackdrop';
-import { useAnimationsFinished } from './utils/useAnimationsFinished';
-import { useOpenChangeComplete } from './utils/useOpenChangeComplete';
-import { getDisabledMountTransitionStyles } from './utils/getDisabledMountTransitionStyles';
-import { POPUP_COLLISION_AVOIDANCE, PATIENT_CLICK_THRESHOLD } from './utils/constants';
-import { ClosePartProvider, useClosePartCount, useClosePartRegistration } from './utils/closePart';
-import { popupStateMapping } from './utils/popupStateMapping';
-import { transitionStatusMapping } from './utils/useTransitionStatus';
-import { COMPOSITE_KEYS } from './utils/composite/keys';
-import { inertValue } from './utils/inertValue';
-import { isHTMLElement } from './utils/dom';
-import {
-	safePolygon,
-	useHoverReferenceInteraction,
-} from './utils/floating/useHoverReferenceInteraction';
-import { useOpenMethodTriggerProps } from './utils/useOpenInteractionType';
-import {
-	triggerOpenStateMapping,
-	pressableTriggerOpenStateMapping,
-} from './utils/popupStateMapping';
-import type { StateAttributesMapping } from './utils/getStateAttributesProps';
-import {
-	createInitialPopupStoreState,
-	createPopupFloatingRootContext,
-	popupStoreSelectors,
-	setPopupOpenState,
-	attachPreventUnmountOnClose,
-	usePopupStore,
-	useInitialOpenSync,
-	useImplicitActiveTrigger,
-	useOpenStateTransitions,
-	usePopupRootSync,
-	usePopupInteractionProps,
-	useTriggerDataForwarding,
-	FOCUSABLE_POPUP_PROPS,
-	createDefaultInitialFocus,
-	type PopupStoreState,
-	type PopupStoreContext,
-} from './utils/popups';
-import { useTriggerFocusGuards } from './utils/popups/useTriggerFocusGuards';
-import { PopupTriggerMap } from './utils/popups/popupTriggerMap';
-import type { InteractionType } from './utils/useEnhancedClickHandler';
-
-const OPEN_DELAY = 300;
-const CLICK_TRIGGER_IDENTIFIER = 'data-base-ui-click-trigger';
-
-// --- Store -------------------------------------------------------------------
-
-export type PopoverState<Payload> = PopupStoreState<Payload> & {
-	disabled: boolean;
-	instantType: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
-	modal: boolean | 'trap-focus';
-	focusManagerModal: boolean;
-	openMethod: InteractionType | null;
-	openChangeReason: string | null;
-	stickIfOpen: boolean;
-	nested: boolean;
-	titleElementId: string | undefined;
-	descriptionElementId: string | undefined;
-	openOnHover: boolean;
-	closeDelay: number;
-	hasViewport: boolean;
-};
-
-type PopoverContext = PopupStoreContext<any> & {
-	readonly popupRef: { current: HTMLElement | null };
-	readonly backdropRef: { current: HTMLDivElement | null };
-	readonly internalBackdropRef: { current: HTMLDivElement | null };
-	readonly triggerFocusTargetRef: { current: HTMLElement | null };
-	readonly beforeContentFocusGuardRef: { current: HTMLElement | null };
-	readonly stickIfOpenTimeout: Timeout;
-};
-
-function createInitialPopoverState<Payload>(): PopoverState<Payload> {
-	return {
-		...createInitialPopupStoreState<Payload>(),
-		disabled: false,
-		modal: false,
-		focusManagerModal: false,
-		instantType: undefined,
-		openMethod: null,
-		openChangeReason: null,
-		titleElementId: undefined,
-		descriptionElementId: undefined,
-		stickIfOpen: true,
-		nested: false,
-		openOnHover: false,
-		closeDelay: 0,
-		hasViewport: false,
-	};
-}
-
-const popoverSelectors = {
-	...popupStoreSelectors,
-	disabled: createSelector((state: PopoverState<unknown>) => state.disabled),
-	instantType: createSelector((state: PopoverState<unknown>) => state.instantType),
-	openMethod: createSelector((state: PopoverState<unknown>) => state.openMethod),
-	openChangeReason: createSelector((state: PopoverState<unknown>) => state.openChangeReason),
-	modal: createSelector((state: PopoverState<unknown>) => state.modal),
-	focusManagerModal: createSelector((state: PopoverState<unknown>) => state.focusManagerModal),
-	stickIfOpen: createSelector((state: PopoverState<unknown>) => state.stickIfOpen),
-	titleElementId: createSelector((state: PopoverState<unknown>) => state.titleElementId),
-	descriptionElementId: createSelector(
-		(state: PopoverState<unknown>) => state.descriptionElementId,
-	),
-	openOnHover: createSelector((state: PopoverState<unknown>) => state.openOnHover),
-	closeDelay: createSelector((state: PopoverState<unknown>) => state.closeDelay),
-	hasViewport: createSelector((state: PopoverState<unknown>) => state.hasViewport),
-};
-
-export class PopoverStore<Payload> extends ReactStore<
-	Readonly<PopoverState<Payload>>,
-	PopoverContext,
-	typeof popoverSelectors
-> {
-	constructor(
-		initialState?: Partial<PopoverState<Payload>>,
-		floatingId?: string | undefined,
-		nested = false,
-	) {
-		const initial = { ...createInitialPopoverState<Payload>(), ...initialState };
-		const triggerElements = new PopupTriggerMap();
-		if (initial.open && initialState?.mounted === undefined) {
-			initial.mounted = true;
-		}
-		initial.floatingRootContext = createPopupFloatingRootContext(
-			triggerElements,
-			floatingId,
-			nested,
-		);
-
-		super(
-			initial,
-			{
-				popupRef: { current: null },
-				backdropRef: { current: null },
-				internalBackdropRef: { current: null },
-				onOpenChange: undefined,
-				onOpenChangeComplete: undefined,
-				triggerFocusTargetRef: { current: null },
-				beforeContentFocusGuardRef: { current: null },
-				stickIfOpenTimeout: new Timeout(),
-				triggerElements,
-			} as PopoverContext,
-			popoverSelectors,
-		);
-	}
-
-	setOpen = (nextOpen: boolean, eventDetails: any) => {
-		const isHover = eventDetails.reason === REASONS.triggerHover;
-		const isKeyboardClick =
-			eventDetails.reason === REASONS.triggerPress &&
-			(eventDetails.event as MouseEvent).detail === 0;
-		const isDismissClose =
-			!nextOpen && (eventDetails.reason === REASONS.escapeKey || eventDetails.reason == null);
-
-		const shouldPreventUnmountOnClose = attachPreventUnmountOnClose(eventDetails);
-
-		const activeTriggerId = this.select('activeTriggerId');
-		if (
-			!nextOpen &&
-			eventDetails.reason === REASONS.closePress &&
-			eventDetails.trigger == null &&
-			activeTriggerId != null
-		) {
-			eventDetails.trigger =
-				this.context.triggerElements.getById(activeTriggerId) ??
-				this.select('activeTriggerElement') ??
-				undefined;
-		}
-
-		this.context.onOpenChange?.(nextOpen, eventDetails);
-		if (eventDetails.isCanceled) {
-			return;
-		}
-
-		(this.state.floatingRootContext as any).dispatchOpenChange(nextOpen, eventDetails);
-
-		const changeState = () => {
-			const updatedState: Partial<PopoverState<Payload>> = {
-				open: nextOpen,
-				openChangeReason: eventDetails.reason,
-			};
-			setPopupOpenState(
-				updatedState as any,
-				nextOpen,
-				eventDetails.trigger,
-				shouldPreventUnmountOnClose(),
-			);
-			this.update(updatedState);
-		};
-
-		if (isHover) {
-			this.set('stickIfOpen', true);
-			this.context.stickIfOpenTimeout.start(PATIENT_CLICK_THRESHOLD, () => {
-				this.set('stickIfOpen', false);
-			});
-			flushSync(changeState);
-		} else {
-			changeState();
-		}
-
-		if (isKeyboardClick || isDismissClose) {
-			this.set('instantType', isKeyboardClick ? 'click' : 'dismiss');
-		} else if (eventDetails.reason === REASONS.focusOut) {
-			this.set('instantType', 'focus');
-		} else {
-			this.set('instantType', undefined);
-		}
-	};
-
-	disposeEffect = () => {
-		return this.context.stickIfOpenTimeout.disposeEffect();
-	};
-
-	static useStore<Payload>(
-		externalStore: PopoverStore<Payload> | undefined,
-		initialState: Partial<PopoverState<Payload>>,
-		slot: symbol | undefined,
-	): PopoverStore<Payload> {
-		const { store, internalStore } = usePopupStore(
-			externalStore as any,
-			(floatingId, nested) => new PopoverStore<Payload>(initialState, floatingId, nested) as any,
-			false,
-			subSlot(slot, 'pop'),
-		);
-		useEffect(
-			() => (internalStore as any)?.disposeEffect(),
-			[internalStore],
-			subSlot(slot, 'dispose'),
-		);
-		return store as unknown as PopoverStore<Payload>;
-	}
-}
-
-// --- Handle ------------------------------------------------------------------
-
-export class PopoverHandle<Payload> {
-	readonly store: PopoverStore<Payload>;
-
-	constructor() {
-		this.store = new PopoverStore<Payload>();
-	}
-
-	open(triggerId: string) {
-		const triggerElement = triggerId
-			? (this.store.context.triggerElements.getById(triggerId) ?? undefined)
-			: undefined;
-		if (triggerId && !triggerElement) {
-			throw new Error(`Base UI: PopoverHandle.open: No trigger found with id "${triggerId}".`);
-		}
-		this.store.setOpen(
-			true,
-			createChangeEventDetails(
-				REASONS.imperativeAction,
-				undefined,
-				triggerElement as HTMLElement | undefined,
-			),
-		);
-	}
-
-	close() {
-		this.store.setOpen(
-			false,
-			createChangeEventDetails(REASONS.imperativeAction, undefined, undefined),
-		);
-	}
-
-	get isOpen() {
-		return this.store.select('open');
-	}
-}
-
-export function createPopoverHandle<Payload>(): PopoverHandle<Payload> {
-	return new PopoverHandle<Payload>();
-}
-
-// --- Contexts ----------------------------------------------------------------
-
-export interface PopoverRootContextValue<Payload = unknown> {
-	store: PopoverStore<Payload>;
-}
-
-const PopoverRootContext = createContext<PopoverRootContextValue | undefined>(undefined);
-
-export function usePopoverRootContext(optional?: boolean): PopoverRootContextValue | undefined {
-	const context = useContext(PopoverRootContext);
-	if (context === undefined && !optional) {
-		throw new Error(
-			'Base UI: PopoverRootContext is missing. Popover parts must be placed within <Popover.Root>.',
-		);
-	}
-	return context;
-}
-
-const PopoverPortalContext = createContext<boolean | undefined>(undefined);
-
-export function usePopoverPortalContext(): boolean {
-	const value = useContext(PopoverPortalContext);
-	if (value === undefined) {
-		throw new Error('Base UI: <Popover.Portal> is missing.');
-	}
-	return value;
-}
-
-export interface PopoverPositionerContextValue {
-	side: Side;
-	align: Align;
-	arrowRef: { current: Element | null };
-	arrowUncentered: boolean;
-	arrowStyles: Record<string, any>;
-	context: any;
-}
-
-const PopoverPositionerContext = createContext<PopoverPositionerContextValue | undefined>(
-	undefined,
-);
-
-export function usePopoverPositionerContext(): PopoverPositionerContextValue {
-	const context = useContext(PopoverPositionerContext);
-	if (!context) {
-		throw new Error(
-			'Base UI: PopoverPositionerContext is missing. PopoverPositioner parts must be placed within <Popover.Positioner>.',
-		);
-	}
-	return context;
-}
-
-// --- Interactions (+ passthrough for the stable-descriptor Provider children) ---
-
-function PopoverInteractions(props: any): any {
-	const slot = S('PopoverInteractions');
-	const { store, modal } = props;
-
-	const floatingRootContext = store.useState('floatingRootContext', subSlot(slot, 'frc'));
-
-	const dismiss = useDismiss(
-		floatingRootContext,
-		{
-			outsidePressEvent: {
-				mouse: modal === 'trap-focus' ? 'sloppy' : 'intentional',
-				touch: 'sloppy',
-			},
-		},
-		subSlot(slot, 'dismiss'),
-	);
-
-	const activeTriggerProps = dismiss.reference ?? EMPTY_OBJECT;
-	const inactiveTriggerProps = dismiss.trigger ?? EMPTY_OBJECT;
-	const popupProps = useMemo(
-		() => mergeProps(FOCUSABLE_POPUP_PROPS, dismiss.floating),
-		[dismiss.floating],
-		subSlot(slot, 'pp'),
-	);
-
-	usePopupInteractionProps(
-		store,
-		{ activeTriggerProps, inactiveTriggerProps, popupProps } as any,
-		subSlot(slot, 'pip'),
-	);
-
-	return null;
-}
-
-// --- Root --------------------------------------------------------------------
-
-function PopoverRootComponent<Payload>(props: any): any {
-	const slot = S('PopoverRoot');
-	const {
-		children,
-		open: openProp,
-		defaultOpen = false,
-		onOpenChange,
-		onOpenChangeComplete,
-		modal = false,
-		handle,
-		actionsRef,
-		triggerId: triggerIdProp,
-		defaultTriggerId: defaultTriggerIdProp = null,
-	} = props;
-
-	const store = PopoverStore.useStore<Payload>(
-		handle?.store,
-		{
-			modal,
-			open: defaultOpen,
-			openProp,
-			activeTriggerId: defaultTriggerIdProp,
-			triggerIdProp,
-		} as Partial<PopoverState<Payload>>,
-		subSlot(slot, 'store'),
-	);
-
-	useInitialOpenSync(
-		store as any,
-		openProp,
-		defaultOpen,
-		defaultTriggerIdProp,
-		subSlot(slot, 'ios'),
-	);
-
-	store.useControlledProp('openProp', openProp, subSlot(slot, 'cp-open'));
-	store.useControlledProp('triggerIdProp', triggerIdProp, subSlot(slot, 'cp-tid'));
-
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const mounted = store.useState('mounted', subSlot(slot, 'mounted'));
-	const payload = store.useState('payload', subSlot(slot, 'payload')) as Payload | undefined;
-	const nested = useFloatingParentNodeId() != null;
-
-	store.useContextCallback('onOpenChange', onOpenChange, subSlot(slot, 'cc-change'));
-	store.useContextCallback(
-		'onOpenChangeComplete',
-		onOpenChangeComplete,
-		subSlot(slot, 'cc-complete'),
-	);
-
-	usePopupRootSync(store as any, open, subSlot(slot, 'rootSync'));
-	useImplicitActiveTrigger(store as any, {}, subSlot(slot, 'iat'));
-	const { forceUnmount } = useOpenStateTransitions(
-		open,
-		store as any,
-		() => {
-			store.update({ stickIfOpen: true, openChangeReason: null });
-		},
-		subSlot(slot, 'ost'),
-	);
-
-	store.useSyncedValues({ modal, nested } as any, subSlot(slot, 'sv'));
-
-	useEffect(
-		() => {
-			if (!open) {
-				store.context.stickIfOpenTimeout.clear();
-			}
-		},
-		[store, open],
-		subSlot(slot, 'e:stick'),
-	);
-
-	const handleImperativeClose = useCallback(
-		() => {
-			store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
-		},
-		[store],
-		subSlot(slot, 'close'),
-	);
-
-	useImperativeHandle(
-		actionsRef,
-		() => ({ unmount: forceUnmount, close: handleImperativeClose }),
-		[forceUnmount, handleImperativeClose],
-		subSlot(slot, 'imp'),
-	);
-
-	const shouldRenderInteractions = open || mounted;
-
-	const contextValue = useMemo(() => ({ store }), [store], subSlot(slot, 'ctx'));
-
-	const resolvedChildren =
-		typeof children === 'function' && !isChildrenBlock(children) ? children({ payload }) : children;
-
-	// `PopoverInteractions` is a headless SIBLING of the children, exactly as Base UI renders it, so
-	// toggling it never disturbs them. Rendering it as a WRAPPER instead swapped the wrapper's
-	// component type on every open, which tore down and rebuilt the whole subtree — including the
-	// trigger, whose element listeners and store registration then pointed at a detached node.
-	const content = [
-		shouldRenderInteractions
-			? createElement(PopoverInteractions, { key: 'interactions', store, modal })
-			: null,
-		createElement(Fragment, { key: 'children', children: resolvedChildren }),
-	];
-
-	return createElement(PopoverRootContext.Provider, {
-		value: contextValue as PopoverRootContextValue,
-		children: content,
-	});
-}
-
-interface PopoverRootProps<Payload> {
-	handle?: PopoverHandle<Payload>;
-	[key: string]: unknown;
-}
-
-function PopoverRoot<Payload = unknown>(props: PopoverRootProps<Payload>): any {
-	const slot = S('PopoverRootWrapper');
-	// Top-level popovers establish a FloatingTree; nested ones reuse the parent's.
-	if (usePopoverRootContext(true)) {
-		return createElement(PopoverRootComponent, props);
-	}
-	return createElement(FloatingTree, {
-		children: createElement(PopoverRootComponent, props),
-	});
-}
-
-// --- Trigger -----------------------------------------------------------------
-
-function PopoverTrigger(componentProps: any): any {
-	const slot = S('PopoverTrigger');
-	const {
-		render,
-		className,
-		style,
-		disabled = false,
-		nativeButton = true,
-		handle,
-		payload,
-		openOnHover = false,
-		delay = OPEN_DELAY,
-		closeDelay = 0,
-		id: idProp,
-		ref,
-		...elementProps
-	} = componentProps;
-
-	const rootContext = usePopoverRootContext(true);
-	const store = (handle?.store ?? rootContext?.store) as PopoverStore<any> | undefined;
-	if (!store) {
-		throw new Error(
-			'Base UI: <Popover.Trigger> must be either used within a <Popover.Root> component or provided with a handle.',
-		);
-	}
-
-	const thisTriggerId = useBaseUiId(idProp, subSlot(slot, 'id'));
-	const isTriggerActive = store.useState('isTriggerActive', subSlot(slot, 'ita'), thisTriggerId);
-	const floatingContext = store.useState('floatingRootContext', subSlot(slot, 'fc'));
-	const isOpenedByThisTrigger = store.useState(
-		'isOpenedByTrigger',
-		subSlot(slot, 'obt'),
-		thisTriggerId,
-	);
-	const popupId = store.useState('triggerPopupId', subSlot(slot, 'tpid'), thisTriggerId);
-
-	const triggerElementRef = useRef<HTMLElement | null>(null, subSlot(slot, 'ter'));
-
-	const { registerTrigger, isMountedByThisTrigger } = useTriggerDataForwarding(
-		thisTriggerId,
-		triggerElementRef,
-		store as any,
-		{ payload, disabled, openOnHover, closeDelay } as any,
-		subSlot(slot, 'tdf'),
-	);
-
-	const openReason = store.useState('openChangeReason', subSlot(slot, 'ocr'));
-	const stickIfOpen = store.useState('stickIfOpen', subSlot(slot, 'sio'));
-	const openMethod = store.useState('openMethod', subSlot(slot, 'om'));
-	const focusManagerModal = store.useState('focusManagerModal', subSlot(slot, 'fmm'));
-
-	const hoverProps = useHoverReferenceInteraction(
-		floatingContext,
-		{
-			enabled:
-				!disabled &&
-				floatingContext != null &&
-				openOnHover &&
-				(openMethod !== 'touch' || openReason !== REASONS.triggerPress),
-			mouseOnly: true,
-			move: false,
-			handleClose: safePolygon(),
-			restMs: delay,
-			delay: { close: closeDelay },
-			triggerElementRef,
-			isActiveTrigger: isTriggerActive,
-			isClosing: () => store.select('transitionStatus') === 'ending',
-		},
-		subSlot(slot, 'hover'),
-	);
-
-	const click = useClick(
-		floatingContext,
-		{ enabled: floatingContext != null, stickIfOpen },
-		subSlot(slot, 'click'),
-	);
-	const interactionTypeProps = useOpenMethodTriggerProps(
-		() => store.select('open'),
-		(interactionType) => {
-			store.set('openMethod', interactionType);
-		},
-		subSlot(slot, 'omt'),
-	);
-
-	const rootTriggerProps = store.useState(
-		'triggerProps',
-		subSlot(slot, 'tp'),
-		isMountedByThisTrigger,
-	);
-
-	const { getButtonProps, buttonRef } = useButton(
-		{ disabled, native: nativeButton },
-		subSlot(slot, 'btn'),
-	);
-
-	const stateAttributesMapping: StateAttributesMapping<{ open: boolean }> = {
-		open(value: boolean) {
-			if (value && openReason === REASONS.triggerPress) {
-				return pressableTriggerOpenStateMapping.open!(value);
-			}
-			return triggerOpenStateMapping.open!(value);
-		},
-	};
-
-	const { preFocusGuardRef, handlePreFocusGuardFocus, handleFocusTargetFocus } =
-		useTriggerFocusGuards(store as any, triggerElementRef, subSlot(slot, 'tfg'));
-
-	const state = { disabled, open: isOpenedByThisTrigger };
-
-	const element = useRenderElement(
-		'button',
-		{ render, className, style },
-		{
-			state,
-			ref: [buttonRef, ref, registerTrigger, triggerElementRef],
-			props: [
-				click.reference,
-				hoverProps,
-				rootTriggerProps,
-				interactionTypeProps,
-				{
-					[CLICK_TRIGGER_IDENTIFIER]: '',
-					id: thisTriggerId,
-					'aria-haspopup': 'dialog',
-					'aria-expanded': isOpenedByThisTrigger,
-					'aria-controls': popupId,
-				},
-				elementProps,
-				getButtonProps,
-			],
-			stateAttributesMapping,
-		},
-		subSlot(slot, 're'),
-	);
-
-	// The trigger's children shape flips between a lone element (closed) and
-	// [guard, element, guard] (open, non-modal). Base UI keeps the trigger's identity across that
-	// flip by wrapping it in a fragment keyed on the trigger id in BOTH branches — without the key
-	// the button is torn down and rebuilt on every open, which detaches the element listeners
-	// (hover open/close) and makes the positioner see a spurious trigger change.
-	const keyedElement = createElement(Fragment, { key: thisTriggerId, children: element });
-
-	if (isMountedByThisTrigger && !focusManagerModal) {
-		// Base UI renders these as static JSX fragment children; octane reconciles a returned array
-		// as a list, so the guards carry stable keys too — otherwise the unkeyed siblings shift the
-		// keyed trigger and it is rebuilt anyway.
-		return [
-			createElement(FocusGuard, {
-				key: `${thisTriggerId}-pre-guard`,
-				ref: preFocusGuardRef,
-				onFocus: handlePreFocusGuardFocus,
-			}),
-			keyedElement,
-			createElement(FocusGuard, {
-				key: `${thisTriggerId}-post-guard`,
-				ref: store.context.triggerFocusTargetRef,
-				onFocus: handleFocusTargetFocus,
-			}),
-		];
-	}
-
-	return keyedElement;
-}
-
-// --- Portal ------------------------------------------------------------------
-
-function PopoverPortal(props: any): any {
-	const slot = S('PopoverPortal');
-	const { keepMounted = false, ref, ...portalProps } = props;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-	const mounted = store.useState('mounted', subSlot(slot, 'mounted'));
-
-	const shouldRender = mounted || keepMounted;
-	if (!shouldRender) {
-		return null;
-	}
-
-	return createElement(PopoverPortalContext.Provider, {
-		value: keepMounted,
-		children: createElement(FloatingPortal, { ref, ...portalProps }),
-	});
-}
-
-// --- Positioner --------------------------------------------------------------
-
-function PopoverPositioner(componentProps: any): any {
-	const slot = S('PopoverPositioner');
-	const {
-		render,
-		className,
-		style,
-		anchor,
-		positionMethod = 'absolute',
-		side = 'bottom',
-		align = 'center',
-		sideOffset = 0,
-		alignOffset = 0,
-		collisionBoundary = 'clipping-ancestors',
-		collisionPadding = 5,
-		arrowPadding = 5,
-		sticky = false,
-		disableAnchorTracking = false,
-		collisionAvoidance = POPUP_COLLISION_AVOIDANCE,
-		ref,
-		...elementProps
-	} = componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-	const keepMounted = usePopoverPortalContext();
-	const nodeId = useFloatingNodeId(undefined, subSlot(slot, 'nodeId'));
-
-	const floatingRootContext = store.useState('floatingRootContext', subSlot(slot, 'frc'));
-	const mounted = store.useState('mounted', subSlot(slot, 'mounted'));
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const openReason = store.useState('openChangeReason', subSlot(slot, 'reason'));
-	const triggerElement = store.useState('activeTriggerElement', subSlot(slot, 'trigger'));
-	const modal = store.useState('modal', subSlot(slot, 'modal'));
-	const openMethod = store.useState('openMethod', subSlot(slot, 'method'));
-	const positionerElement = store.useState('positionerElement', subSlot(slot, 'posEl'));
-	const instantType = store.useState('instantType', subSlot(slot, 'instant'));
-	const transitionStatus = store.useState('transitionStatus', subSlot(slot, 'trans'));
-	const hasViewport = store.useState('hasViewport', subSlot(slot, 'viewport'));
-
-	const prevTriggerElementRef = useRef<Element | null>(null, subSlot(slot, 'prevTrigger'));
-
-	const runOnceAnimationsFinish = useAnimationsFinished(
-		positionerElement,
-		false,
-		false,
-		subSlot(slot, 'anim'),
-	);
-
-	const positioning = useAnchorPositioning(
-		{
-			anchor,
-			floatingRootContext,
-			positionMethod,
-			mounted,
-			side,
-			sideOffset,
-			align,
-			alignOffset,
-			arrowPadding,
-			collisionBoundary,
-			collisionPadding,
-			sticky,
-			disableAnchorTracking,
-			keepMounted,
-			nodeId,
-			collisionAvoidance,
-			adaptiveOrigin: hasViewport ? adaptiveOrigin : undefined,
-		},
-		subSlot(slot, 'positioning'),
-	);
-
-	const domReference = floatingRootContext.useState('domReferenceElement', subSlot(slot, 'domref'));
-
-	// When the current trigger element changes, enable transitions on the positioner temporarily.
-	useLayoutEffect(
-		() => {
-			const currentTriggerElement = domReference;
-			const prevTriggerElement = prevTriggerElementRef.current;
-
-			if (currentTriggerElement) {
-				prevTriggerElementRef.current = currentTriggerElement;
-			}
-
-			if (
-				prevTriggerElement &&
-				currentTriggerElement &&
-				currentTriggerElement !== prevTriggerElement
-			) {
-				store.set('instantType', undefined);
-				const ac = new AbortController();
-				runOnceAnimationsFinish(() => {
-					store.set('instantType', 'trigger-change');
-				}, ac.signal);
-
-				return () => {
-					ac.abort();
-				};
-			}
-
-			return undefined;
-		},
-		[domReference, runOnceAnimationsFinish, store],
-		subSlot(slot, 'e:trigger'),
-	);
-
-	useAnchoredPopupScrollLock(
-		open && modal === true && openReason !== REASONS.triggerHover,
-		openMethod === 'touch',
-		positionerElement,
-		triggerElement,
-	);
-
-	const setPositionerElement = useCallback(
-		(element: HTMLElement | null) => {
-			store.set('positionerElement', element);
-		},
-		[store],
-		subSlot(slot, 'setPosEl'),
-	);
-
-	const state: PopoverPositionerState = {
-		open,
-		side: positioning.side,
-		align: positioning.align,
-		anchorHidden: positioning.anchorHidden,
-		instant: instantType,
-	};
-
-	const element = usePositioner(
-		componentProps,
-		state,
-		{
-			styles: positioning.positionerStyles,
-			transitionStatus,
-			props: elementProps,
-			refs: [ref, setPositionerElement],
-			hidden: !mounted,
-			inert: !open,
-		},
-		subSlot(slot, 'positioner'),
-	);
-
-	return createElement(PopoverPositionerContext.Provider, {
-		value: positioning as unknown as PopoverPositionerContextValue,
-		// Octane reconciles an ARRAY child as a keyed list, so both slots carry a key. Only the
-		// modal path renders the backdrop, which is why a non-modal popover never warned.
-		children: [
-			mounted && modal === true && openReason !== REASONS.triggerHover
-				? createElement(InternalBackdrop, {
-						key: 'internal-backdrop',
-						ref: store.context.internalBackdropRef,
-						inert: inertValue(!open),
-						cutout: triggerElement,
-					})
-				: null,
-			createElement(FloatingNode, { key: 'floating-node', id: nodeId, children: element }),
-		],
-	});
-}
-
-interface PopoverPositionerState {
-	open: boolean;
-	side: Side;
-	align: Align;
-	anchorHidden: boolean;
-	instant: string | undefined;
-}
-
-// --- Popup -------------------------------------------------------------------
-
-const popoverPopupStateAttributesMapping = {
-	...popupStateMapping,
-	...transitionStatusMapping,
-};
-
-function PopoverPopup(componentProps: any): any {
-	const slot = S('PopoverPopup');
-	const { render, className, style, initialFocus, finalFocus, ref, ...elementProps } =
-		componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-
-	const positioner = usePopoverPositionerContext();
-	// No Toolbar context in this phase; composite key-stop is toolbar-only.
-	const insideToolbar = false;
-	const { context: closePartContext, hasClosePart } = useClosePartCount();
-
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const openMethod = store.useState('openMethod', subSlot(slot, 'method'));
-	const instantType = store.useState('instantType', subSlot(slot, 'instant'));
-	const transitionStatus = store.useState('transitionStatus', subSlot(slot, 'trans'));
-	const popupProps = store.useState('popupProps', subSlot(slot, 'popupProps'));
-	const titleId = store.useState('titleElementId', subSlot(slot, 'titleId'));
-	const descriptionId = store.useState('descriptionElementId', subSlot(slot, 'descId'));
-	const modal = store.useState('modal', subSlot(slot, 'modal'));
-	const mounted = store.useState('mounted', subSlot(slot, 'mounted'));
-	const openReason = store.useState('openChangeReason', subSlot(slot, 'reason'));
-	const activeTriggerElement = store.useState('activeTriggerElement', subSlot(slot, 'trigger'));
-	const floatingContext = store.useState('floatingRootContext', subSlot(slot, 'frc'));
-	const floatingId = floatingContext.useState('floatingId', subSlot(slot, 'fid'));
-	const disabled = store.useState('disabled', subSlot(slot, 'disabled'));
-	const openOnHover = store.useState('openOnHover', subSlot(slot, 'hover'));
-	const closeDelay = store.useState('closeDelay', subSlot(slot, 'closeDelay'));
-
-	const popupId = elementProps.id ?? floatingId;
-
-	useOpenChangeComplete(
-		{
-			open,
-			ref: store.context.popupRef,
-			onComplete() {
-				if (open) {
-					store.context.onOpenChangeComplete?.(true);
-				}
-			},
-		},
-		subSlot(slot, 'occ'),
-	);
-
-	useHoverFloatingInteraction(
-		floatingContext,
-		{ enabled: openOnHover && !disabled, closeDelay },
-		subSlot(slot, 'hoverInteraction'),
-	);
-
-	const resolvedInitialFocus =
-		initialFocus === undefined ? createDefaultInitialFocus(store.context.popupRef) : initialFocus;
-
-	const focusManagerModal = modal !== false && hasClosePart;
-	store.useSyncedValue('focusManagerModal', focusManagerModal, subSlot(slot, 'fmm'));
-
-	const setPopupElement = useCallback(
-		(element: HTMLElement | null) => {
-			store.set('popupElement', element);
-		},
-		[store],
-		subSlot(slot, 'setPopupEl'),
-	);
-
-	const state: PopoverPopupState = {
-		open,
-		side: positioner.side,
-		align: positioner.align,
-		instant: instantType,
-		transitionStatus,
-	};
-
-	const element = useRenderElement(
-		'div',
-		componentProps,
-		{
-			state,
-			ref: [ref, store.context.popupRef, setPopupElement],
-			props: [
-				popupProps,
-				{
-					id: popupId,
-					role: 'dialog',
-					...FOCUSABLE_POPUP_PROPS,
-					'aria-labelledby': titleId,
-					'aria-describedby': descriptionId,
-					onKeyDown(event: any) {
-						if (insideToolbar && COMPOSITE_KEYS.has(event.key)) {
-							event.stopPropagation();
-						}
-					},
-				},
-				getDisabledMountTransitionStyles(transitionStatus),
-				elementProps,
-			],
-			stateAttributesMapping: popoverPopupStateAttributesMapping,
-		},
-		subSlot(slot, 're'),
-	);
-
-	return createElement(FloatingFocusManager, {
-		context: floatingContext,
-		openInteractionType: openMethod,
-		modal: focusManagerModal,
-		disabled: !mounted || openReason === REASONS.triggerHover,
-		initialFocus: resolvedInitialFocus,
-		returnFocus: finalFocus,
-		restoreFocus: 'popup',
-		previousFocusableElement: isHTMLElement(activeTriggerElement)
-			? activeTriggerElement
-			: undefined,
-		nextFocusableElement: store.context.triggerFocusTargetRef,
-		beforeContentFocusGuardRef: store.context.beforeContentFocusGuardRef,
-		children: createElement(ClosePartProvider, { value: closePartContext, children: element }),
-	});
-}
-
-interface PopoverPopupState {
-	open: boolean;
-	side: Side;
-	align: Align;
-	transitionStatus: any;
-	instant: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
-}
-
-// --- Arrow -------------------------------------------------------------------
-
-function PopoverArrow(componentProps: any): any {
-	const slot = S('PopoverArrow');
-	const { render, className, style, ref, ...elementProps } = componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const { arrowRef, side, align, arrowUncentered, arrowStyles } = usePopoverPositionerContext();
-
-	const state: PopoverArrowState = {
-		open,
-		side,
-		align,
-		uncentered: arrowUncentered,
-	};
-
-	return useRenderElement(
-		'div',
-		componentProps,
-		{
-			state,
-			ref: [ref, arrowRef],
-			props: [{ style: arrowStyles, 'aria-hidden': true }, elementProps],
-			stateAttributesMapping: popupStateMapping,
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-interface PopoverArrowState {
-	open: boolean;
-	side: Side;
-	align: Align;
-	uncentered: boolean;
-}
-
-// --- Backdrop ----------------------------------------------------------------
-
-const popoverBackdropStateAttributesMapping = {
-	...popupStateMapping,
-	...transitionStatusMapping,
-};
-
-function PopoverBackdrop(props: any): any {
-	const slot = S('PopoverBackdrop');
-	const { render, className, style, ref, ...elementProps } = props;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-
-	const open = store.useState('open', subSlot(slot, 'open'));
-	const mounted = store.useState('mounted', subSlot(slot, 'mounted'));
-	const transitionStatus = store.useState('transitionStatus', subSlot(slot, 'trans'));
-	const openReason = store.useState('openChangeReason', subSlot(slot, 'reason'));
-
-	const state: PopoverBackdropState = {
-		open,
-		transitionStatus,
-	};
-
-	return useRenderElement(
-		'div',
-		props,
-		{
-			state,
-			ref: [store.context.backdropRef, ref],
-			props: [
-				{
-					role: 'presentation',
-					hidden: !mounted,
-					style: {
-						pointerEvents: openReason === REASONS.triggerHover ? 'none' : undefined,
-						userSelect: 'none',
-						WebkitUserSelect: 'none',
-					},
-				},
-				elementProps,
-			],
-			stateAttributesMapping: popoverBackdropStateAttributesMapping,
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-interface PopoverBackdropState {
-	open: boolean;
-	transitionStatus: any;
-}
-
-// --- Title -------------------------------------------------------------------
-
-function PopoverTitle(componentProps: any): any {
-	const slot = S('PopoverTitle');
-	const { render, className, style, ref, ...elementProps } = componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-
-	const id = useBaseUiId(elementProps.id, subSlot(slot, 'id'));
-
-	store.useSyncedValueWithCleanup('titleElementId', id, subSlot(slot, 'sync'));
-
-	return useRenderElement(
-		'h2',
-		componentProps,
-		{
-			ref,
-			props: [{ id }, elementProps],
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-// --- Description -------------------------------------------------------------
-
-function PopoverDescription(componentProps: any): any {
-	const slot = S('PopoverDescription');
-	const { render, className, style, ref, ...elementProps } = componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-
-	const id = useBaseUiId(elementProps.id, subSlot(slot, 'id'));
-
-	store.useSyncedValueWithCleanup('descriptionElementId', id, subSlot(slot, 'sync'));
-
-	return useRenderElement(
-		'p',
-		componentProps,
-		{
-			ref,
-			props: [{ id }, elementProps],
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-// --- Close -------------------------------------------------------------------
-
-function PopoverClose(componentProps: any): any {
-	const slot = S('PopoverClose');
-	const {
-		render,
-		className,
-		style,
-		disabled = false,
-		nativeButton = true,
-		ref,
-		...elementProps
-	} = componentProps;
-
-	const { buttonRef, getButtonProps } = useButton(
-		{ disabled, focusableWhenDisabled: false, native: nativeButton },
-		subSlot(slot, 'btn'),
-	);
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-	useClosePartRegistration();
-
-	return useRenderElement(
-		'button',
-		componentProps,
-		{
-			ref: [ref, buttonRef],
-			props: [
-				{
-					onClick(event: any) {
-						store.setOpen(false, createChangeEventDetails(REASONS.closePress, event));
-					},
-				},
-				elementProps,
-				getButtonProps,
-			],
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-// --- Viewport ----------------------------------------------------------------
-
-export const PopoverViewportCssVars = {
-	/**
-	 * The width of the parent popup when the previous content was rendered. Placed on the
-	 * 'previous' container so the popup's dimensions can be frozen while content animates.
-	 */
-	popupWidth: '--popup-width',
-	/** The height of the parent popup when the previous content was rendered. */
-	popupHeight: '--popup-height',
-} as const;
-
-const viewportStateAttributesMapping: StateAttributesMapping<any> = {
-	activationDirection: (value: string | undefined) =>
-		value ? { 'data-activation-direction': value } : null,
-};
-
-// A viewport for displaying content transitions. Only needed when one popup can be opened by
-// multiple triggers, its content changes per trigger, and switching between them is animated.
-function PopoverViewport(componentProps: any): any {
-	const slot = S('PopoverViewport');
-	const { render, className, style, children, ref, ...elementProps } = componentProps;
-
-	const { store } = usePopoverRootContext() as PopoverRootContextValue;
-	const { side } = usePopoverPositionerContext();
-
-	const instantType = store.useState('instantType', subSlot(slot, 'instant'));
-
-	const { children: childrenToRender, state: viewportState } = usePopupViewport(
-		{ store, side, cssVars: PopoverViewportCssVars, children },
-		subSlot(slot, 'vp'),
-	);
-
-	const state = {
-		activationDirection: viewportState.activationDirection,
-		transitioning: viewportState.transitioning,
-		instant: instantType,
-	};
-
-	return useRenderElement(
-		'div',
-		{ render, className, style },
-		{
-			state,
-			ref,
-			props: [elementProps, { children: childrenToRender }],
-			stateAttributesMapping: viewportStateAttributesMapping,
-		},
-		subSlot(slot, 're'),
-	);
-}
-
-// --- Namespace ---------------------------------------------------------------
-
-export const Popover = {
-	Root: PopoverRoot,
-	Trigger: PopoverTrigger,
-	Portal: PopoverPortal,
-	Positioner: PopoverPositioner,
-	Popup: PopoverPopup,
-	Viewport: PopoverViewport,
-	Arrow: PopoverArrow,
-	Backdrop: PopoverBackdrop,
-	Title: PopoverTitle,
-	Description: PopoverDescription,
-	Close: PopoverClose,
-	createHandle: createPopoverHandle,
-	Handle: PopoverHandle,
-};