@octanejs/base-ui 0.1.50 → 0.1.51

package/src/popover/root/PopoverRoot.tsrx

@@ -0,0 +1,262 @@
+'use client';
+import * as React from 'octane';
+import { fastComponent } from '@octanejs/base-ui-utils/fastHooks';
+import { useDismiss, FloatingTree } from '../../floating-ui-react';
+import { PopoverRootContext, usePopoverRootContext } from './PopoverRootContext';
+import { PopoverStore, type State as PopoverStoreState } from '../store/PopoverStore';
+import type { PopoverHandle } from '../store/PopoverHandle';
+import {
+	createChangeEventDetails,
+	type BaseUIChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
+import {
+	PopupHandleAttachment,
+	useImplicitActiveTrigger,
+	usePopupRootStore,
+	useOpenStateTransitions,
+	usePopupInteractionProps,
+	usePopupRootSync,
+	type PayloadChildRenderFunction,
+} from '../../utils/popups';
+
+const PopoverRootComponent = fastComponent(function PopoverRootComponent<Payload>({
+	props,
+}: {
+	props: PopoverRoot.Props<Payload>;
+}) {
+	const {
+		children,
+		open: openProp,
+		defaultOpen = false,
+		onOpenChange,
+		onOpenChangeComplete,
+		modal = false,
+		handle,
+		triggerId: triggerIdProp,
+		defaultTriggerId: defaultTriggerIdProp = null,
+	} = props;
+
+	const store = usePopoverRootStore(handle, {
+		modal,
+		open: defaultOpen,
+		openProp,
+		activeTriggerId: defaultTriggerIdProp,
+		triggerIdProp,
+	});
+
+	store.useControlledProp('openProp', openProp);
+	store.useControlledProp('triggerIdProp', triggerIdProp);
+
+	const open = store.useState('open');
+	const mounted = store.useState('mounted');
+	const payload = store.useState('payload') as Payload | undefined;
+
+	store.useContextCallback('onOpenChange', onOpenChange);
+	store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
+
+	usePopupRootSync(store, open);
+	useImplicitActiveTrigger(store);
+	const { forceUnmount } = useOpenStateTransitions(open, store, () => {
+		store.update({ stickIfOpen: true, openChangeReason: null });
+	});
+
+	store.useSyncedValues({
+		modal,
+	});
+
+	React.useEffect(() => {
+		if (!open) {
+			store.context.stickIfOpenTimeout.clear();
+		}
+	}, [store, open]);
+
+	React.useImperativeHandle(
+		props.actionsRef,
+		() => ({
+			unmount: forceUnmount,
+			close: () => store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction)),
+		}),
+		[forceUnmount, store],
+	);
+
+	const shouldRenderInteractions = open || mounted;
+
+	return (
+		<PopoverRootContext.Provider value={store as PopoverRootContext<unknown>}>
+			{handle && <PopupHandleAttachment handle={handle} store={store} />}
+			{shouldRenderInteractions && <PopoverInteractions store={store} modal={modal} />}
+			{typeof children === 'function' && !React.isChildrenBlock(children)
+				? children({ payload })
+				: children}
+		</PopoverRootContext.Provider>
+	);
+});
+
+/**
+ * Groups all parts of the popover.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
+ */
+export function PopoverRoot<Payload = unknown>(props: PopoverRoot.Props<Payload>) {
+	if (usePopoverRootContext(true)) {
+		return <PopoverRootComponent props={props} />;
+	}
+
+	return (
+		<FloatingTree>
+			<PopoverRootComponent props={props} />
+		</FloatingTree>
+	);
+}
+
+function usePopoverRootStore<Payload>(
+	handle: PopoverHandle<Payload> | undefined,
+	initialState: Partial<PopoverStoreState<Payload>>,
+) {
+	// The store is owned by this Root instance and created exactly once. It is not tied to the handle:
+	// the handle attaches to it, so swapping the handle re-attaches rather than recreating state.
+	// Default values are only initial values; controlled values and root state are synced after creation.
+	const store = usePopupRootStore(
+		(floatingId, nested) => new PopoverStore<Payload>(initialState, floatingId, nested),
+	);
+
+	// Popover-specific: dispose the patient-click timeout held in the store's context on unmount.
+	React.useEffect(() => store.context.stickIfOpenTimeout.disposeEffect(), [store]);
+
+	return store;
+}
+
+export interface PopoverRootState {}
+
+export interface PopoverRootProps<Payload = unknown> {
+	/**
+	 * Whether the popover is initially open.
+	 *
+	 * To render a controlled popover, use the `open` prop instead.
+	 * @default false
+	 */
+	defaultOpen?: boolean | undefined;
+	/**
+	 * Whether the popover is currently open.
+	 */
+	open?: boolean | undefined;
+	/**
+	 * Event handler called when the popover is opened or closed.
+	 */
+	onOpenChange?:
+		((open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void) | undefined;
+	/**
+	 * Event handler called after any animations complete when the popover is opened or closed.
+	 */
+	onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `unmount`: Manually unmounts the popover.
+	 * Call this after any externally controlled closing animation finishes.
+	 * - `close`: Closes the popover imperatively when called.
+	 */
+	actionsRef?: React.RefObject<PopoverRoot.Actions | null> | undefined;
+	/**
+	 * Determines if the popover enters a modal state when open.
+	 * - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.
+	 * - `false`: user interaction with the rest of the document is allowed.
+	 * - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
+	 *
+	 * On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+	 *
+	 * When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered
+	 * inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as
+	 * Tailwind's `sr-only` utility.
+	 *
+	 * When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch
+	 * screen readers can escape the popup.
+	 * @default false
+	 */
+	modal?: boolean | 'trap-focus' | undefined;
+	/**
+	 * ID of the trigger that the popover is associated with.
+	 * This is useful in conjunction with the `open` prop to create a controlled popover.
+	 * There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).
+	 */
+	triggerId?: string | null | undefined;
+	/**
+	 * ID of the trigger that the popover is associated with.
+	 * This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
+	 */
+	defaultTriggerId?: string | null | undefined;
+	/**
+	 * A handle to associate the popover with a trigger.
+	 * If specified, allows external triggers to control the popover's open state.
+	 */
+	handle?: PopoverHandle<Payload> | undefined;
+	/**
+	 * The content of the popover.
+	 * This can be a regular React node or a render function that receives the `payload` of the active trigger.
+	 */
+	children?: NonNullable<React.OctaneNode> | null | undefined | PayloadChildRenderFunction<Payload>;
+}
+
+export interface PopoverRootActions {
+	unmount: () => void;
+	close: () => void;
+}
+
+export type PopoverRootChangeEventReason =
+	| typeof REASONS.triggerHover
+	| typeof REASONS.triggerFocus
+	| typeof REASONS.triggerPress
+	| typeof REASONS.outsidePress
+	| typeof REASONS.escapeKey
+	| typeof REASONS.closePress
+	| typeof REASONS.focusOut
+	| typeof REASONS.imperativeAction
+	| typeof REASONS.none;
+export type PopoverRootChangeEventDetails =
+	BaseUIChangeEventDetails<PopoverRoot.ChangeEventReason> & {
+		preventUnmountOnClose(): void;
+	};
+
+export namespace PopoverRoot {
+	export type State = PopoverRootState;
+	export type Props<Payload = unknown> = PopoverRootProps<Payload>;
+	export type Actions = PopoverRootActions;
+	export type ChangeEventReason = PopoverRootChangeEventReason;
+	export type ChangeEventDetails = PopoverRootChangeEventDetails;
+}
+
+function PopoverInteractions({
+	store,
+	modal,
+}: {
+	store: PopoverStore<any>;
+	modal: boolean | 'trap-focus';
+}) {
+	const floatingRootContext = store.useState('floatingRootContext');
+
+	const dismiss = useDismiss(floatingRootContext, {
+		outsidePressEvent: {
+			// Ensure `aria-hidden` on outside elements is removed immediately
+			// on outside press when trapping focus.
+			mouse: modal === 'trap-focus' ? 'sloppy' : 'intentional',
+			touch: 'sloppy',
+		},
+	});
+
+	// `useDismiss` is not given an `enabled` option, so it always returns both prop bags. Restore
+	// the `EMPTY_OBJECT` fallbacks if that ever changes: the store fields are non-optional.
+	// `dismiss.trigger` is always the same object as `dismiss.reference`.
+	const triggerProps = dismiss.reference!;
+	// PopoverPopup already spreads `FOCUSABLE_POPUP_PROPS` directly, so the popup
+	// props only need to carry the dismiss handlers.
+	const popupProps = dismiss.floating!;
+
+	usePopupInteractionProps(store, {
+		activeTriggerProps: triggerProps,
+		inactiveTriggerProps: triggerProps,
+		popupProps,
+	});
+
+	return null;
+}

package/src/popover/root/PopoverRootContext.ts

@@ -0,0 +1,20 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { PopoverStore } from '../store/PopoverStore';
+
+export type PopoverRootContext<Payload = unknown> = PopoverStore<Payload>;
+
+export const PopoverRootContext = React.createContext<PopoverRootContext | undefined>(undefined);
+
+export function usePopoverRootContext(optional?: false): PopoverRootContext;
+export function usePopoverRootContext(optional: true): PopoverRootContext | undefined;
+export function usePopoverRootContext(optional?: boolean) {
+	const context = React.useContext(PopoverRootContext);
+	if (context === undefined && !optional) {
+		throw new Error(
+			'Base UI: PopoverRootContext is missing. Popover parts must be placed within <Popover.Root>.',
+		);
+	}
+	return context;
+}

package/src/popover/store/PopoverHandle.ts

@@ -0,0 +1,54 @@
+import { type PopoverStore, createNullPopoverStore, type PopoverHandleStore } from './PopoverStore';
+import { BasePopupHandle } from '../../utils/popups/popupHandle';
+
+/**
+ * Controls a Popover imperatively and associates detached `Popover.Trigger` components with a
+ * `Popover.Root`. Create one with `Popover.createHandle()` and pass it to the `handle` prop of the
+ * root and of any triggers rendered outside of it.
+ *
+ * The imperative methods take effect only while a root using this handle is mounted; calls made
+ * before a root attaches (or after it unmounts) are ignored.
+ */
+export class PopoverHandle<Payload> extends BasePopupHandle<
+	PopoverHandleStore<Payload>,
+	PopoverStore<Payload>
+> {
+	constructor() {
+		super(createNullPopoverStore<Payload>(), 'Popover');
+	}
+
+	/**
+	 * Opens the popover and associates it with the trigger with the given id.
+	 *
+	 * This method should only be called in an event handler or an effect (not during rendering).
+	 *
+	 * @param triggerId ID of the trigger to associate with the popover. The trigger must be a matching
+	 * `Popover.Trigger` with this handle passed as a prop.
+	 */
+	open(triggerId: string) {
+		this.openByTrigger(triggerId);
+	}
+
+	/**
+	 * Closes the popover.
+	 *
+	 * This method should only be called in an event handler or an effect (not during rendering).
+	 */
+	close() {
+		this.closePopup();
+	}
+
+	/**
+	 * Whether the popover is currently open. Returns `false` while no root is attached to the handle.
+	 */
+	get isOpen() {
+		return this.attachedStore?.select('open') ?? false;
+	}
+}
+
+/**
+ * Creates a new handle to connect a Popover.Root with detached Popover.Trigger components.
+ */
+export function createPopoverHandle<Payload>(): PopoverHandle<Payload> {
+	return new PopoverHandle<Payload>();
+}

package/src/popover/store/PopoverStore.ts

@@ -0,0 +1,229 @@
+'use client';
+import type * as React from 'octane';
+import * as ReactDOM from 'octane';
+import { ReactStore } from '@octanejs/base-ui-utils/store';
+import { Timeout } from '@octanejs/base-ui-utils/useTimeout';
+import { NOOP } from '@octanejs/base-ui-utils/empty';
+import { type InteractionType } from '@octanejs/base-ui-utils/useEnhancedClickHandler';
+import { type PopoverRoot } from '../root/PopoverRoot.tsrx';
+import { REASONS } from '../../internals/reasons';
+import { NullStore } from '../../utils/NullStore';
+import {
+	attachPreventUnmountOnClose,
+	createInitialPopupStoreState,
+	type PopupStoreContext,
+	popupStoreSelectors,
+	type PopupStoreState,
+	PopupTriggerMap,
+	type PopupTriggerStoreKeys,
+	createPopupOpenState,
+} from '../../utils/popups';
+import { PATIENT_CLICK_THRESHOLD } from '../../internals/constants';
+import type { AdaptiveOriginMiddleware } from '../../utils/adaptiveOriginConstants';
+
+export type State<Payload> = PopupStoreState<Payload> & {
+	disabled: boolean;
+	instantType: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
+	modal: boolean | 'trap-focus';
+	focusManagerModal: boolean;
+	openMethod: InteractionType | null;
+	openChangeReason: PopoverRoot.ChangeEventReason | null;
+	stickIfOpen: boolean;
+	titleElementId: string | undefined;
+	descriptionElementId: string | undefined;
+	openOnHover: boolean;
+	closeDelay: number;
+	adaptiveOrigin: AdaptiveOriginMiddleware | undefined;
+};
+
+type Context = PopupStoreContext<PopoverRoot.ChangeEventDetails> & {
+	readonly popupRef: React.RefObject<HTMLElement | null>;
+	readonly triggerFocusTargetRef: React.RefObject<HTMLElement | null>;
+	readonly beforeContentFocusGuardRef: React.RefObject<HTMLElement | null>;
+	readonly stickIfOpenTimeout: Timeout;
+};
+
+const selectors = {
+	...popupStoreSelectors,
+	disabled: (state: State<unknown>) => state.disabled,
+	instantType: (state: State<unknown>) => state.instantType,
+	openMethod: (state: State<unknown>) => state.openMethod,
+	openChangeReason: (state: State<unknown>) => state.openChangeReason,
+	modal: (state: State<unknown>) => state.modal,
+	focusManagerModal: (state: State<unknown>) => state.focusManagerModal,
+	stickIfOpen: (state: State<unknown>) => state.stickIfOpen,
+	titleElementId: (state: State<unknown>) => state.titleElementId,
+	descriptionElementId: (state: State<unknown>) => state.descriptionElementId,
+	openOnHover: (state: State<unknown>) => state.openOnHover,
+	closeDelay: (state: State<unknown>) => state.closeDelay,
+	adaptiveOrigin: (state: State<unknown>): AdaptiveOriginMiddleware | undefined =>
+		state.adaptiveOrigin,
+};
+
+type Selectors = typeof selectors;
+
+/**
+ * The store view that detached handle-backed triggers read from. Both the real `PopoverStore` and
+ * the inert fallback store satisfy it, so a trigger can read from whichever store the handle
+ * currently exposes. Narrowed to the members a trigger actually uses — the trigger-data members plus
+ * `setOpen` (called by the focus guards) — so the exposed surface can't bypass the open-change
+ * pipeline; on the detached fallback store every one of these mutations is a no-op.
+ */
+export type PopoverHandleStore<Payload> = Pick<
+	PopoverStore<Payload>,
+	PopupTriggerStoreKeys | 'setOpen'
+>;
+
+export class PopoverStore<Payload> extends ReactStore<
+	Readonly<State<Payload>>,
+	Context,
+	Selectors
+> {
+	constructor(
+		initialState: Partial<State<Payload>>,
+		floatingId: string | undefined,
+		nested: boolean,
+	) {
+		const triggerElements = new PopupTriggerMap();
+		super(
+			createInitialState<Payload>(initialState, triggerElements, floatingId, nested),
+			createInitialContext(triggerElements),
+			selectors,
+		);
+	}
+
+	setOpen = (
+		nextOpen: boolean,
+		eventDetails: Omit<PopoverRoot.ChangeEventDetails, 'preventUnmountOnClose'>,
+	) => {
+		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 as PopoverRoot.ChangeEventDetails,
+		);
+
+		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 as PopoverRoot.ChangeEventDetails);
+
+		if (eventDetails.isCanceled) {
+			return;
+		}
+
+		this.state.floatingRootContext.dispatchOpenChange(nextOpen, eventDetails);
+
+		const changeState = () => {
+			const popupOpenState = createPopupOpenState(
+				this.state,
+				nextOpen,
+				eventDetails.trigger,
+				shouldPreventUnmountOnClose(),
+			) as ReturnType<typeof createPopupOpenState> & {
+				openChangeReason: PopoverRoot.ChangeEventReason;
+			};
+
+			popupOpenState.openChangeReason = eventDetails.reason;
+			this.update(popupOpenState);
+		};
+
+		if (isHover) {
+			// Only allow "patient" clicks to close the popover if it's open.
+			// If they clicked within 500ms of the popover opening, keep it open.
+			this.set('stickIfOpen', true);
+			this.context.stickIfOpenTimeout.start(PATIENT_CLICK_THRESHOLD, () => {
+				this.set('stickIfOpen', false);
+			});
+
+			ReactDOM.flushSync(changeState);
+		} else {
+			changeState();
+		}
+
+		let instantType: State<Payload>['instantType'];
+		if (isKeyboardClick) {
+			instantType = 'click';
+		} else if (isDismissClose) {
+			instantType = 'dismiss';
+		} else if (eventDetails.reason === REASONS.focusOut) {
+			instantType = 'focus';
+		}
+		this.set('instantType', instantType);
+	};
+}
+
+/**
+ * Creates the inert fallback store used by detached handle-backed triggers while no
+ * `Popover.Root` is attached. It preserves a popover-specific trigger registry in context so
+ * detached triggers can register before migrating to the live root store. `setOpen` is a no-op
+ * (matching the inert reads/writes of `NullStore`), so a trigger can hand the store to focus-guard
+ * helpers that expect `setOpen` without it ever taking effect while detached.
+ */
+export function createNullPopoverStore<Payload>(): PopoverHandleStore<Payload> {
+	const triggerElements = new PopupTriggerMap();
+
+	const store = new NullStore<Readonly<State<Payload>>, Context, Selectors>(
+		Object.freeze(createInitialState<Payload>(undefined, triggerElements)),
+		Object.freeze(createInitialContext(triggerElements)),
+		selectors,
+	);
+	return Object.assign(store, { setOpen: NOOP });
+}
+
+function createInitialState<Payload>(
+	initialState: Partial<State<Payload>> | undefined,
+	triggerElements: PopupTriggerMap,
+	floatingId?: string | undefined,
+	nested = false,
+): State<Payload> {
+	const state: State<Payload> = {
+		...createInitialPopupStoreState<Payload>(triggerElements, floatingId, nested),
+		disabled: false,
+		modal: false,
+		focusManagerModal: false,
+		instantType: undefined,
+		openMethod: null,
+		openChangeReason: null,
+		titleElementId: undefined,
+		descriptionElementId: undefined,
+		stickIfOpen: true,
+		openOnHover: false,
+		closeDelay: 0,
+		adaptiveOrigin: undefined,
+		...initialState,
+	};
+
+	if (state.open && initialState?.mounted === undefined) {
+		state.mounted = true;
+	}
+
+	return state;
+}
+
+function createInitialContext(triggerElements: PopupTriggerMap): Context {
+	return {
+		popupRef: { current: null } as React.RefObject<HTMLElement | null>,
+		onOpenChange: undefined,
+		onOpenChangeComplete: undefined,
+		triggerFocusTargetRef: { current: null } as React.RefObject<HTMLElement | null>,
+		beforeContentFocusGuardRef: { current: null } as React.RefObject<HTMLElement | null>,
+		stickIfOpenTimeout: new Timeout(),
+		triggerElements,
+	};
+}

package/src/popover/title/PopoverTitle.tsrx

@@ -0,0 +1,46 @@
+'use client';
+import type * as React from 'octane';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { useBaseUiId } from '../../internals/useBaseUiId';
+
+/**
+ * A heading that labels the popover.
+ * Renders an `<h2>` element.
+ *
+ * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
+ */
+export const PopoverTitle = function PopoverTitle(
+	componentPropsWithRef: React.PropsWithoutRef<PopoverTitle.Props> & {
+		ref?: React.Ref<HTMLHeadingElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+
+	const store = usePopoverRootContext();
+
+	const id = useBaseUiId(elementProps.id);
+
+	store.useSyncedValueWithCleanup('titleElementId', id);
+
+	const element = useRenderElement('h2', componentProps, {
+		ref: forwardedRef,
+		props: [{ id }, elementProps],
+	});
+
+	return element;
+};
+
+export interface PopoverTitleState {}
+
+export interface PopoverTitleProps extends BaseUIComponentProps<
+	'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6',
+	PopoverTitleState
+> {}
+
+export namespace PopoverTitle {
+	export type State = PopoverTitleState;
+	export type Props = PopoverTitleProps;
+}