@octanejs/base-ui 0.1.50 → 0.1.51

package/src/utils/popups/popupTriggerMap.ts

@@ -1,62 +1,136 @@
-// Ported verbatim from .base-ui/packages/react/src/utils/popups/popupTriggerMap.ts (v1.6.0).
-// Tracks a popup's trigger elements by id (a Set for membership + a Map for id lookup). Pure —
-// the dev-only invariant check is dropped (functional outcomes only).
-export class PopupTriggerMap {
-	private elementsSet: Set<Element>;
+/**
+ * Development-only reverse index of element to registered id, keyed by the owning map.
+ *
+ * Registration would otherwise have to scan every entry to detect an element claimed by two ids,
+ * making the mount of many triggers sharing one handle quadratic. Kept module-scoped, lazily
+ * initialized, and read only from `process.env.NODE_ENV` guards so production builds drop it along
+ * with the checks.
+ */
+let devElementIdsByMap: WeakMap<PopupTriggerMap, WeakMap<Element, string>> | undefined;
+
+function getDevElementIds(map: PopupTriggerMap) {
+	devElementIdsByMap ??= new WeakMap();
+
+	let elementIds = devElementIdsByMap.get(map);
+	if (!elementIds) {
+		elementIds = new WeakMap();
+		devElementIdsByMap.set(map, elementIds);
+	}
+	return elementIds;
+}
 
+/**
+ * Data structure to keep track of popup trigger elements by their IDs.
+ *
+ * Element lookups iterate the id map rather than maintaining a parallel Set. Registration is O(1),
+ * while `hasElement` and `hasMatchingElement` are linear in the number of triggers.
+ */
+export class PopupTriggerMap {
 	private idMap: Map<string, Element>;
 
 	constructor() {
-		this.elementsSet = new Set();
 		this.idMap = new Map();
 	}
 
-	add(id: string, element: Element) {
-		const existingElement = this.idMap.get(id);
-		if (existingElement === element) {
-			return;
-		}
-		if (existingElement !== undefined) {
-			this.elementsSet.delete(existingElement);
+	/**
+	 * Adds a trigger element with the given ID.
+	 *
+	 * Note: The provided element is assumed to not be registered under multiple IDs.
+	 */
+	public add(id: string, element: Element) {
+		if (process.env.NODE_ENV !== 'production') {
+			const elementIds = getDevElementIds(this);
+
+			const existingId = elementIds.get(element);
+			if (existingId !== undefined && existingId !== id) {
+				// TODO: fix mui/no-guarded-throw
+				// eslint-disable-next-line mui/no-guarded-throw
+				throw new Error(
+					'Base UI: A trigger element cannot be registered under multiple IDs in PopupTriggerMap.',
+				);
+			}
+
+			// Reusing an id for a different element evicts the previous one, so it must lose its claim
+			// on the id or a later registration under a different id would be reported as a duplicate.
+			const previousElement = this.idMap.get(id);
+			if (previousElement !== undefined && previousElement !== element) {
+				elementIds.delete(previousElement);
+			}
+
+			elementIds.set(element, id);
 		}
-		this.elementsSet.add(element);
+
 		this.idMap.set(id, element);
 	}
 
-	delete(id: string) {
-		const element = this.idMap.get(id);
-		if (element) {
-			this.elementsSet.delete(element);
-			this.idMap.delete(id);
+	/**
+	 * Removes the trigger element with the given ID.
+	 */
+	public delete(id: string) {
+		if (process.env.NODE_ENV !== 'production') {
+			const element = this.idMap.get(id);
+			if (element !== undefined) {
+				devElementIdsByMap?.get(this)?.delete(element);
+			}
 		}
+
+		this.idMap.delete(id);
 	}
 
-	hasElement(element: Element): boolean {
-		return this.elementsSet.has(element);
+	/**
+	 * Whether the given element is registered as a trigger.
+	 */
+	public hasElement(element: Element): boolean {
+		for (const registered of this.idMap.values()) {
+			if (registered === element) {
+				return true;
+			}
+		}
+
+		return false;
 	}
 
-	hasMatchingElement(predicate: (el: Element) => boolean): boolean {
-		for (const element of this.elementsSet) {
+	/**
+	 * Whether there is a registered trigger element matching the given predicate.
+	 */
+	public hasMatchingElement(predicate: (el: Element) => boolean): boolean {
+		for (const element of this.idMap.values()) {
 			if (predicate(element)) {
 				return true;
 			}
 		}
+
 		return false;
 	}
 
-	getById(id: string): Element | undefined {
+	/**
+	 * Returns the trigger element associated with the given ID, or undefined if no such element exists.
+	 */
+	public getById(id: string): Element | undefined {
 		return this.idMap.get(id);
 	}
 
-	entries(): IterableIterator<[string, Element]> {
+	/**
+	 * Returns an iterable of all registered trigger entries, where each entry is a tuple of [id, element].
+	 */
+	public entries(): IterableIterator<[string, Element]> {
 		return this.idMap.entries();
 	}
 
-	elements(): IterableIterator<Element> {
-		return this.elementsSet.values();
+	/**
+	 * Returns an iterable of all registered trigger elements.
+	 */
+	public elements(): IterableIterator<Element> {
+		return this.idMap.values();
 	}
 
-	get size(): number {
+	/**
+	 * Returns the number of registered trigger elements.
+	 */
+	public get size(): number {
 		return this.idMap.size;
 	}
 }
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/utils/popups/store.ts

@@ -1,44 +1,108 @@
-// Ported from .base-ui/packages/react/src/utils/popups/store.ts (v1.6.0). The state shape, initial
-// state, floating-root-context factory, and selectors shared by EVERY popup store (Dialog/Popover/
-// Tooltip/Menu/PreviewCard). Pure — octane adaptations are only import paths + `HTMLProps` inlined.
-import { createSelector } from '../store/createSelector';
-import { EMPTY_OBJECT } from '../empty';
-import type { FloatingRootContext } from '../floating/types';
-import { FloatingRootStore } from '../floating/FloatingRootStore';
-import { getEmptyRootContext } from '../floating/getEmptyRootContext';
-import type { TransitionStatus } from '../useTransitionStatus';
-import { PopupTriggerMap } from './popupTriggerMap';
-
-type HTMLProps = Record<string, any>;
+import type * as React from 'octane';
+import type { ReactStore } from '@octanejs/base-ui-utils/store';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import type { FloatingRootContext } from '../../floating-ui-react';
+import { FloatingRootStore } from '../../floating-ui-react/components/FloatingRootStore';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+import type { PopupTriggerMap } from './popupTriggerMap';
+import type { HTMLProps } from '../../internals/types';
 
+/**
+ * State common to all popup stores.
+ */
 export type PopupStoreState<Payload> = {
+	/**
+	 * Whether the popup is open (internal state).
+	 */
 	open: boolean;
+	/**
+	 * Whether the popup is open (external prop).
+	 */
 	readonly openProp: boolean | undefined;
+	/**
+	 * Whether the popup should be mounted in the DOM.
+	 * This usually follows `open` but can be different during exit transitions.
+	 */
 	mounted: boolean;
+	/**
+	 * The current enter/exit transition status of the popup.
+	 */
 	transitionStatus: TransitionStatus;
+
 	floatingRootContext: FloatingRootContext;
 	floatingId: string | undefined;
+	/**
+	 * Number of trigger elements currently registered for this popup.
+	 */
 	triggerCount: number;
+	/**
+	 * Whether to prevent unmounting the popup when closed.
+	 * Useful for interacting with JS animation libraries that control unmounting themselves.
+	 */
 	preventUnmountingOnClose: boolean;
+
+	/**
+	 * Optional payload set by the trigger.
+	 */
 	payload: Payload | undefined;
+
+	/**
+	 * ID of the currently active trigger.
+	 */
 	activeTriggerId: string | null;
+	/**
+	 * The currently active trigger DOM element.
+	 */
 	activeTriggerElement: Element | null;
+	/**
+	 * ID of the trigger (external prop).
+	 */
 	readonly triggerIdProp: string | null | undefined;
+	/**
+	 * The popup DOM element.
+	 */
 	popupElement: HTMLElement | null;
+	/**
+	 * The positioner DOM element.
+	 */
 	positionerElement: HTMLElement | null;
+
+	/**
+	 * Props to spread onto the active trigger element.
+	 */
 	activeTriggerProps: HTMLProps;
+	/**
+	 * Props to spread onto inactive trigger elements.
+	 */
 	inactiveTriggerProps: HTMLProps;
+	/**
+	 * Props to spread onto the popup element.
+	 */
 	popupProps: HTMLProps;
 };
 
-export function createInitialPopupStoreState<Payload>(): PopupStoreState<Payload> {
+export function createInitialPopupStoreState<Payload>(
+	triggerElements: PopupTriggerMap,
+	floatingId?: string | undefined,
+	nested = false,
+): PopupStoreState<Payload> {
 	return {
 		open: false,
 		openProp: undefined,
 		mounted: false,
 		transitionStatus: undefined,
-		floatingRootContext: getEmptyRootContext(),
-		floatingId: undefined,
+		floatingRootContext: new FloatingRootStore({
+			open: false,
+			transitionStatus: undefined,
+			floatingElement: null,
+			referenceElement: null,
+			triggerElements,
+			floatingId,
+			syncOnly: true,
+			nested,
+			onOpenChange: undefined,
+		}),
+		floatingId,
 		triggerCount: 0,
 		preventUnmountingOnClose: false,
 		payload: undefined,
@@ -53,43 +117,35 @@ export function createInitialPopupStoreState<Payload>(): PopupStoreState<Payload
 	};
 }
 
-export function createPopupFloatingRootContext(
-	triggerElements: PopupTriggerMap,
-	floatingId?: string | undefined,
-	nested = false,
-) {
-	return new FloatingRootStore({
-		open: false,
-		transitionStatus: undefined,
-		floatingElement: null,
-		referenceElement: null,
-		triggerElements,
-		floatingId,
-		syncOnly: true,
-		nested,
-		onOpenChange: undefined,
-	});
-}
-
 export type PopupStoreContext<ChangeEventDetails> = {
+	/**
+	 * Map of registered trigger elements.
+	 */
 	readonly triggerElements: PopupTriggerMap;
-	readonly popupRef: { current: HTMLElement | null };
+	/**
+	 * Reference to the popup element.
+	 */
+	readonly popupRef: React.RefObject<HTMLElement | null>;
+	/**
+	 * Callback fired when the open state changes.
+	 */
 	onOpenChange?: ((open: boolean, eventDetails: ChangeEventDetails) => void) | undefined;
+	/**
+	 * Callback fired when the open state change animation completes.
+	 */
 	onOpenChangeComplete: ((open: boolean) => void) | undefined;
 };
 
 type S = PopupStoreState<unknown>;
 
-const activeTriggerIdSelector = createSelector(
-	(state: S) => state.triggerIdProp ?? state.activeTriggerId,
-);
+const activeTriggerIdSelector = (state: S) => state.triggerIdProp ?? state.activeTriggerId;
 
-const openSelector = createSelector((state: S) => state.openProp ?? state.open);
+const openSelector = (state: S) => state.openProp ?? state.open;
 
-const popupIdSelector = createSelector((state: S) => {
+const popupIdSelector = (state: S) => {
 	const popupId = state.popupElement?.id ?? state.floatingId;
 	return popupId || undefined;
-});
+};
 
 function triggerOwnsOpenPopup(state: S, triggerId: string | undefined) {
 	return (
@@ -101,6 +157,7 @@ function triggerOwnsOpenPopupOrIsOnlyTrigger(state: S, triggerId: string | undef
 	if (triggerOwnsOpenPopup(state, triggerId)) {
 		return true;
 	}
+
 	return (
 		triggerId !== undefined &&
 		openSelector(state) &&
@@ -111,37 +168,60 @@ function triggerOwnsOpenPopupOrIsOnlyTrigger(state: S, triggerId: string | undef
 
 export const popupStoreSelectors = {
 	open: openSelector,
-	mounted: createSelector((state: S) => state.mounted),
-	transitionStatus: createSelector((state: S) => state.transitionStatus),
-	floatingRootContext: createSelector((state: S) => state.floatingRootContext),
-	triggerCount: createSelector((state: S) => state.triggerCount),
-	preventUnmountingOnClose: createSelector((state: S) => state.preventUnmountingOnClose),
-	payload: createSelector((state: S) => state.payload),
+	mounted: (state: S) => state.mounted,
+	transitionStatus: (state: S) => state.transitionStatus,
+	floatingRootContext: (state: S) => state.floatingRootContext,
+	triggerCount: (state: S) => state.triggerCount,
+	preventUnmountingOnClose: (state: S) => state.preventUnmountingOnClose,
+	payload: (state: S) => state.payload,
+
 	activeTriggerId: activeTriggerIdSelector,
-	activeTriggerElement: createSelector((state: S) =>
-		state.mounted ? state.activeTriggerElement : null,
-	),
+	activeTriggerElement: (state: S) => (state.mounted ? state.activeTriggerElement : null),
 	popupId: popupIdSelector,
-	isTriggerActive: createSelector(
-		(state: S, triggerId: string | undefined) =>
-			triggerId !== undefined && activeTriggerIdSelector(state) === triggerId,
-	),
-	isOpenedByTrigger: createSelector((state: S, triggerId: string | undefined) =>
+	/**
+	 * Whether the trigger with the given ID was used to open the popup.
+	 */
+	isTriggerActive: (state: S, triggerId: string | undefined) =>
+		triggerId !== undefined && activeTriggerIdSelector(state) === triggerId,
+	/**
+	 * Whether the popup is open and was activated by a trigger with the given ID.
+	 */
+	isOpenedByTrigger: (state: S, triggerId: string | undefined) =>
 		triggerOwnsOpenPopup(state, triggerId),
-	),
-	isMountedByTrigger: createSelector(
-		(state: S, triggerId: string | undefined) =>
-			triggerId !== undefined && activeTriggerIdSelector(state) === triggerId && state.mounted,
-	),
-	triggerProps: createSelector((state: S, isActive: boolean) =>
+	/**
+	 * Whether the popup is mounted and was activated by a trigger with the given ID.
+	 */
+	isMountedByTrigger: (state: S, triggerId: string | undefined) =>
+		triggerId !== undefined && activeTriggerIdSelector(state) === triggerId && state.mounted,
+	triggerProps: (state: S, isActive: boolean) =>
 		isActive ? state.activeTriggerProps : state.inactiveTriggerProps,
-	),
-	triggerPopupId: createSelector((state: S, triggerId: string | undefined) =>
+	/**
+	 * Popup id for the trigger that currently owns the open popup.
+	 */
+	triggerPopupId: (state: S, triggerId: string | undefined) =>
 		triggerOwnsOpenPopupOrIsOnlyTrigger(state, triggerId) ? popupIdSelector(state) : undefined,
-	),
-	popupProps: createSelector((state: S) => state.popupProps),
-	popupElement: createSelector((state: S) => state.popupElement),
-	positionerElement: createSelector((state: S) => state.positionerElement),
+	popupProps: (state: S) => state.popupProps,
+
+	popupElement: (state: S) => state.popupElement,
+	positionerElement: (state: S) => state.positionerElement,
 };
 
 export type PopupStoreSelectors = typeof popupStoreSelectors;
+
+/**
+ * Store members a detached handle-backed trigger reads or invokes for trigger registration and data
+ * forwarding. `set`/`update` are included only for trigger-count and trigger-data bookkeeping; on a
+ * detached (inert) store they are intentionally no-ops, so a write through them is not guaranteed to
+ * be durable. Component handle-store views Pick these from their concrete store (preserving its
+ * context and selectors) and add any component-specific trigger-invoked members such as `setOpen`.
+ */
+export type PopupTriggerStoreKeys = 'context' | 'select' | 'set' | 'state' | 'update' | 'useState';
+
+/**
+ * The subset of a popup store that trigger registration and data forwarding rely on. Narrow enough
+ * that an inert store can be passed while detached.
+ */
+export type PopupTriggerDataStore<State extends PopupStoreState<unknown>> = Pick<
+	ReactStore<Readonly<State>, PopupStoreContext<never>, PopupStoreSelectors>,
+	PopupTriggerStoreKeys
+>;

package/src/utils/popups/usePopupHandleStore.ts

@@ -0,0 +1,37 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useSyncExternalStore } from 'octane';
+import { NOOP } from '@octanejs/base-ui-utils/empty';
+import type { PopupHandleStoreProvider } from './popupHandle';
+
+/**
+ * Reads the store currently exposed by a popup handle and subscribes to store-pointer changes.
+ * Detached triggers use this to follow a handle as a root attaches or detaches: while no root is
+ * attached, the handle exposes its fallback store; once a root attaches, subscribers re-render and
+ * read from the live root store.
+ *
+ * Returns `undefined` when no handle is provided so callers can fall back to their root context.
+ *
+ * @param handle The popup handle to read from, or `undefined` when the trigger is not handle-bound.
+ */
+export function usePopupHandleStore<HandleStore>(
+	handle: PopupHandleStoreProvider<HandleStore> | undefined,
+): HandleStore | undefined {
+	const subscribe = React.useCallback(
+		(listener: () => void) => {
+			if (handle === undefined) {
+				return NOOP;
+			}
+
+			return handle.subscribeStore(listener);
+		},
+		[handle],
+	);
+
+	const getSnapshot = React.useCallback(() => {
+		return handle === undefined ? undefined : handle.store;
+	}, [handle]);
+
+	return useSyncExternalStore(subscribe, getSnapshot, () => handle?.serverStore);
+}

package/src/utils/popups/useTriggerFocusGuards.ts

@@ -1,63 +1,77 @@
-// Ported from .base-ui/packages/react/src/utils/popups/useTriggerFocusGuards.ts (v1.6.0), octane-
-// adapted (native events; `ReactDOM.flushSync` → octane `flushSync`; the ref threads a slot). Focus
-// guards placed around an OPEN popup's trigger (Popover/Menu): tabbing out of the trigger closes the
-// popup and moves focus to the right neighbour.
-import { useRef, flushSync } from 'octane';
-
-import { subSlot } from '../../internal';
-import { contains } from '../floating/element';
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
 import {
+	contains,
+	type FocusableElement,
 	getNextTabbable,
 	getTabbableAfterElement,
 	getTabbableBeforeElement,
 	isOutsideEvent,
-	type FocusableElement,
-} from '../floating/tabbable';
-import { createChangeEventDetails, REASONS } from '../createChangeEventDetails';
+} from '../../floating-ui-react/utils';
+import {
+	type BaseUIChangeEventDetails,
+	createChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
 
+/**
+ * Minimal store interface required by the focus guard hook.
+ * Both PopoverStore and MenuStore satisfy this interface.
+ */
 interface TriggerFocusGuardStore {
-	setOpen(open: boolean, eventDetails: any): void;
+	setOpen(open: boolean, eventDetails: BaseUIChangeEventDetails<typeof REASONS.focusOut>): void;
 	select(key: 'positionerElement'): HTMLElement | null;
 	context: {
-		readonly beforeContentFocusGuardRef: { current: HTMLElement | null };
-		readonly triggerFocusTargetRef: { current: HTMLElement | null };
+		readonly beforeContentFocusGuardRef: React.RefObject<HTMLElement | null>;
+		readonly triggerFocusTargetRef: React.RefObject<HTMLElement | null>;
 	};
 }
 
+/**
+ * Provides focus guard handlers for popup triggers (Popover, Menu).
+ *
+ * When the popup is open, invisible focus guard elements are placed before and after
+ * the trigger. These handlers close the popup and move focus to the appropriate
+ * tabbable element when the guards receive focus (i.e. when the user tabs out).
+ */
 export function useTriggerFocusGuards(
 	store: TriggerFocusGuardStore,
-	triggerElementRef: { current: HTMLElement | null },
-	slot: symbol | undefined,
+	triggerElementRef: React.RefObject<HTMLElement | null>,
 ) {
-	const preFocusGuardRef = useRef<HTMLElement | null>(null, subSlot(slot, 'pre'));
+	const preFocusGuardRef = React.useRef<HTMLElement | null>(null);
 
-	function handlePreFocusGuardFocus(event: any) {
-		flushSync(() => {
+	function handlePreFocusGuardFocus(event: React.FocusEvent) {
+		ReactDOM.flushSync(() => {
 			store.setOpen(
 				false,
 				createChangeEventDetails(REASONS.focusOut, event, event.currentTarget as HTMLElement),
 			);
 		});
+
 		const previousTabbable: FocusableElement | null = getTabbableBeforeElement(
 			preFocusGuardRef.current,
 		);
 		previousTabbable?.focus();
 	}
 
-	function handleFocusTargetFocus(event: any) {
+	function handleFocusTargetFocus(event: React.FocusEvent) {
 		const positionerElement = store.select('positionerElement');
 		if (positionerElement && isOutsideEvent(event, positionerElement)) {
 			store.context.beforeContentFocusGuardRef.current?.focus();
 		} else {
-			flushSync(() => {
+			ReactDOM.flushSync(() => {
 				store.setOpen(
 					false,
 					createChangeEventDetails(REASONS.focusOut, event, event.currentTarget as HTMLElement),
 				);
 			});
+
 			let nextTabbable = getTabbableAfterElement(
 				store.context.triggerFocusTargetRef.current || triggerElementRef.current,
 			);
+
 			while (nextTabbable !== null && contains(positionerElement, nextTabbable)) {
 				const prevTabbable = nextTabbable;
 				nextTabbable = getNextTabbable(nextTabbable);
@@ -65,6 +79,7 @@ export function useTriggerFocusGuards(
 					break;
 				}
 			}
+
 			nextTabbable?.focus();
 		}
 	}

package/src/utils/resolveAriaLabelledBy.ts

@@ -1,4 +1,5 @@
-// Ported verbatim from .base-ui/packages/react/src/utils/resolveAriaLabelledBy.ts.
+'use client';
+
 export function getDefaultLabelId(id: string | null | undefined) {
 	return id == null ? undefined : `${id}-label`;
 }

package/src/utils/resolveClassName.ts

@@ -1,8 +1,13 @@
-// Ported from .base-ui/packages/react/src/utils/resolveClassName.ts.
-// A className that is a function is called with the component state.
+/**
+ * If the provided className is a string, it will be returned as is.
+ * Otherwise, the function will call the className function with the state as the first argument.
+ *
+ * @param className
+ * @param state
+ */
 export function resolveClassName<State>(
 	className: string | ((state: State) => string | undefined) | undefined,
 	state: State,
-): string | undefined {
+) {
 	return typeof className === 'function' ? className(state) : className;
 }

package/src/utils/resolveRef.ts

@@ -1,10 +1,14 @@
-// Ported from .base-ui/packages/react/src/utils/resolveRef.ts. Returns a ref object's
-// `.current`, or the value itself if it's already an element.
+import type * as React from 'octane';
+/**
+ * If the provided argument is a ref object, returns its `current` value.
+ * Otherwise, returns the argument itself.
+ */
 export function resolveRef<T extends HTMLElement | null | undefined>(
-	maybeRef: T | { current: T },
+	maybeRef: T | React.RefObject<T>,
 ): T {
 	if (maybeRef == null) {
-		return maybeRef as T;
+		return maybeRef;
 	}
+
 	return 'current' in maybeRef ? maybeRef.current : maybeRef;
 }

package/src/utils/resolveStyle.ts

@@ -1,10 +1,14 @@
-// Ported from .base-ui/packages/react/src/utils/resolveStyle.ts.
-// A style that is a function is called with the component state.
-type CSSProperties = Record<string, any>;
-
+import type * as React from 'octane';
+/**
+ * If the provided style is an object, it will be returned as is.
+ * Otherwise, the function will call the style function with the state as the first argument.
+ *
+ * @param style
+ * @param state
+ */
 export function resolveStyle<State>(
-	style: CSSProperties | ((state: State) => CSSProperties | undefined) | undefined,
+	style: React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined,
 	state: State,
-): CSSProperties | undefined {
+) {
 	return typeof style === 'function' ? style(state) : style;
 }