@octanejs/base-ui 0.1.49 → 0.1.51

package/src/popover/popup/PopoverPopup.tsrx

@@ -0,0 +1,188 @@
+'use client';
+import * as React from 'octane';
+import type { InteractionType } from '@octanejs/base-ui-utils/useEnhancedClickHandler';
+import { isHTMLElement } from '@floating-ui/utils/dom';
+import { FloatingFocusManager, useHoverFloatingInteraction } from '../../floating-ui-react';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { usePopoverPositionerContext } from '../positioner/PopoverPositionerContext';
+import type { Side, Align } from '../../internals/useAnchorPositioning';
+import type { BaseUIComponentProps } from '../../internals/types';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+import { popupTransitionStateMapping } from '../../utils/popupStateMapping';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import { REASONS } from '../../internals/reasons';
+import { COMPOSITE_KEYS } from '../../internals/composite/composite';
+import { useToolbarRootContext } from '../../toolbar/root/ToolbarRootContext';
+import { getDisabledMountTransitionStyles } from '../../internals/getDisabledMountTransitionStyles';
+import { ClosePartContext, useClosePartCount } from '../../utils/closePart.tsrx';
+import { FOCUSABLE_POPUP_PROPS, createDefaultInitialFocus } from '../../utils/popups';
+
+/**
+ * A container for the popover contents.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
+ */
+export const PopoverPopup = function PopoverPopup(
+	componentPropsWithRef: React.PropsWithoutRef<PopoverPopup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, initialFocus, finalFocus, ...elementProps } = componentProps;
+
+	const store = usePopoverRootContext();
+
+	const positioner = usePopoverPositionerContext();
+	const insideToolbar = useToolbarRootContext(true) != null;
+	const { context: closePartContext, hasClosePart } = useClosePartCount();
+
+	const open = store.useState('open');
+	const openMethod = store.useState('openMethod');
+	const instantType = store.useState('instantType');
+	const transitionStatus = store.useState('transitionStatus');
+	const popupProps = store.useState('popupProps');
+	const titleId = store.useState('titleElementId');
+	const descriptionId = store.useState('descriptionElementId');
+	const modal = store.useState('modal');
+	const mounted = store.useState('mounted');
+	const openReason = store.useState('openChangeReason');
+	const activeTriggerElement = store.useState('activeTriggerElement');
+	const floatingContext = store.useState('floatingRootContext');
+	const floatingId = floatingContext.useState('floatingId');
+	const disabled = store.useState('disabled');
+	const openOnHover = store.useState('openOnHover');
+	const closeDelay = store.useState('closeDelay');
+
+	useOpenChangeComplete({
+		open,
+		ref: store.context.popupRef,
+		onComplete() {
+			if (open) {
+				store.context.onOpenChangeComplete?.(true);
+			}
+		},
+	});
+
+	useHoverFloatingInteraction(floatingContext, { enabled: openOnHover && !disabled, closeDelay });
+
+	const resolvedInitialFocus =
+		initialFocus === undefined ? createDefaultInitialFocus(store.context.popupRef) : initialFocus;
+
+	const focusManagerModal = modal !== false && hasClosePart;
+	store.useSyncedValue('focusManagerModal', focusManagerModal);
+
+	const setPopupElement = store.useStateSetter('popupElement');
+
+	const state: PopoverPopupState = {
+		open,
+		side: positioner.side,
+		align: positioner.align,
+		instant: instantType,
+		transitionStatus,
+	};
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		ref: [forwardedRef, store.context.popupRef, setPopupElement],
+		props: [
+			popupProps,
+			{
+				id: floatingId,
+				role: 'dialog',
+				...FOCUSABLE_POPUP_PROPS,
+				'aria-labelledby': titleId,
+				'aria-describedby': descriptionId,
+				onKeyDown(event) {
+					if (insideToolbar && COMPOSITE_KEYS.has(event.key)) {
+						event.stopPropagation();
+					}
+				},
+			},
+			getDisabledMountTransitionStyles(transitionStatus),
+			elementProps,
+		],
+		stateAttributesMapping: popupTransitionStateMapping,
+	});
+
+	return (
+		<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}
+		>
+			<ClosePartContext.Provider value={closePartContext}>{element}</ClosePartContext.Provider>
+		</FloatingFocusManager>
+	);
+};
+
+export interface PopoverPopupState {
+	/**
+	 * Whether the popover is currently open.
+	 */
+	open: boolean;
+	/**
+	 * The side of the anchor the component is placed on.
+	 */
+	side: Side;
+	/**
+	 * The alignment of the component relative to the anchor.
+	 */
+	align: Align;
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+	/**
+	 * Whether transitions should be skipped.
+	 */
+	instant: 'dismiss' | 'click' | 'focus' | 'trigger-change' | undefined;
+}
+
+export interface PopoverPopupProps extends BaseUIComponentProps<'div', PopoverPopupState> {
+	/**
+	 * Determines the element to focus when the popover is opened.
+	 * By default, focus moves to the first tabbable element inside the popup, except when the popover
+	 * is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
+	 *
+	 * - `false`: Do not move focus.
+	 * - `true`: Move focus based on the default behavior (first tabbable element or popup).
+	 * - `RefObject`: Move focus to the ref element.
+	 * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+	 *   Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+	 */
+	initialFocus?:
+		| boolean
+		| React.RefObject<HTMLElement | null>
+		| ((openType: InteractionType) => void | boolean | HTMLElement | null)
+		| undefined;
+	/**
+	 * Determines the element to focus when the popover is closed.
+	 *
+	 * - `false`: Do not move focus.
+	 * - `true`: Move focus based on the default behavior (trigger or previously focused element).
+	 * - `RefObject`: Move focus to the ref element.
+	 * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+	 *   Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+	 */
+	finalFocus?:
+		| boolean
+		| React.RefObject<HTMLElement | null>
+		| ((closeType: InteractionType) => void | boolean | HTMLElement | null)
+		| undefined;
+}
+
+export namespace PopoverPopup {
+	export type State = PopoverPopupState;
+	export type Props = PopoverPopupProps;
+}

package/src/popover/popup/PopoverPopupCssVars.ts

@@ -0,0 +1,8 @@
+/**
+ * The width of the popup.
+ */
+export const popupWidth = '--popup-width';
+/**
+ * The height of the popup.
+ */
+export const popupHeight = '--popup-height';

package/src/popover/popup/PopoverPopupDataAttributes.ts

@@ -0,0 +1,33 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the popup is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the popup is closed.
+ */
+export const closed = CommonPopupDataAttributes.closed;
+/**
+ * Present when the popup begins animating in.
+ */
+export const startingStyle = CommonPopupDataAttributes.startingStyle;
+/**
+ * Present when the popup is animating out.
+ */
+export const endingStyle = CommonPopupDataAttributes.endingStyle;
+/**
+ * Indicates which side the popup is positioned relative to the trigger.
+ * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+ */
+export const side = CommonPopupDataAttributes.side;
+/**
+ * Indicates how the popup is aligned relative to specified side.
+ * @type {'start' | 'center' | 'end'}
+ */
+export const align = CommonPopupDataAttributes.align;
+/**
+ * Present if animations should be instant.
+ * @type {'click' | 'dismiss' | 'focus' | 'trigger-change'}
+ */
+export const instant = 'data-instant';

package/src/popover/portal/PopoverPortal.tsrx

@@ -0,0 +1,54 @@
+'use client';
+import * as React from 'octane';
+import { FloatingPortal } from '../../floating-ui-react';
+import { type BaseUIComponentProps } from '../../internals/types';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { PopoverPortalContext } from './PopoverPortalContext';
+
+/**
+ * A portal element that moves the popup to a different part of the DOM.
+ * By default, the portal element is appended to `<body>`.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
+ */
+export const PopoverPortal = function PopoverPortal(
+	propsWithRef: React.PropsWithoutRef<PopoverPortal.Props> & { ref?: React.Ref<HTMLDivElement> },
+) {
+	const { ref: forwardedRef = null, ...props } = propsWithRef;
+	const { keepMounted = false, ...portalProps } = props;
+
+	const store = usePopoverRootContext();
+	const mounted = store.useState('mounted');
+
+	const shouldRender = mounted || keepMounted;
+	if (!shouldRender) {
+		return null;
+	}
+
+	return (
+		<PopoverPortalContext.Provider value={keepMounted}>
+			<FloatingPortal ref={forwardedRef} {...portalProps} />
+		</PopoverPortalContext.Provider>
+	);
+};
+
+export interface PopoverPortalState {}
+
+export interface PopoverPortalProps extends BaseUIComponentProps<'div', PopoverPortalState> {
+	/**
+	 * Whether to keep the portal mounted in the DOM while the popup is hidden.
+	 * @default false
+	 */
+	keepMounted?: boolean | undefined;
+	/**
+	 * A parent element to render the portal element into.
+	 */
+	container?:
+		HTMLElement | ShadowRoot | React.RefObject<HTMLElement | ShadowRoot | null> | null | undefined;
+}
+
+export namespace PopoverPortal {
+	export type State = PopoverPortalState;
+	export type Props = PopoverPortalProps;
+}

package/src/popover/portal/PopoverPortalContext.ts

@@ -0,0 +1,13 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+export const PopoverPortalContext = React.createContext<boolean | undefined>(undefined);
+
+export function usePopoverPortalContext() {
+	const value = React.useContext(PopoverPortalContext);
+	if (value === undefined) {
+		throw new Error('Base UI: <Popover.Portal> is missing.');
+	}
+	return value;
+}

package/src/popover/positioner/PopoverPositioner.tsrx

@@ -0,0 +1,196 @@
+'use client';
+import * as React from 'octane';
+import { inertValue } from '@octanejs/base-ui-utils/inertValue';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { FloatingNode, useFloatingNodeId } from '../../floating-ui-react';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { PopoverPositionerContext } from './PopoverPositionerContext';
+import {
+	useAnchorPositioning,
+	type Side,
+	type Align,
+	type UseAnchorPositioningSharedParameters,
+} from '../../internals/useAnchorPositioning';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { usePopoverPortalContext } from '../portal/PopoverPortalContext';
+import { InternalBackdrop } from '../../utils/InternalBackdrop.tsrx';
+import { REASONS } from '../../internals/reasons';
+import { POPUP_COLLISION_AVOIDANCE } from '../../internals/constants';
+import { useAnimationsFinished } from '../../internals/useAnimationsFinished';
+import { usePositioner } from '../../utils/usePositioner.tsrx';
+import { useAnchoredPopupScrollLock } from '../../utils/useAnchoredPopupScrollLock';
+
+/**
+ * Positions the popover against the trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
+ */
+export const PopoverPositioner = function PopoverPositioner(
+	componentPropsWithRef: React.PropsWithoutRef<PopoverPositioner.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		render,
+		className,
+		style,
+		anchor,
+		// `useAnchorPositioning` applies the same defaults to the undefined values; the names
+		// remain destructured to exclude the props from `elementProps`.
+		positionMethod,
+		side,
+		align,
+		sideOffset,
+		alignOffset,
+		collisionBoundary = 'clipping-ancestors',
+		collisionPadding,
+		arrowPadding,
+		sticky,
+		disableAnchorTracking = false,
+		collisionAvoidance = POPUP_COLLISION_AVOIDANCE,
+		...elementProps
+	} = componentProps;
+
+	const store = usePopoverRootContext();
+	const keepMounted = usePopoverPortalContext();
+	const nodeId = useFloatingNodeId();
+
+	const floatingRootContext = store.useState('floatingRootContext');
+	const mounted = store.useState('mounted');
+	const open = store.useState('open');
+	const openReason = store.useState('openChangeReason');
+	const triggerElement = store.useState('activeTriggerElement');
+	const modal = store.useState('modal');
+	const openMethod = store.useState('openMethod');
+	const positionerElement = store.useState('positionerElement');
+	const instantType = store.useState('instantType');
+	const transitionStatus = store.useState('transitionStatus');
+	const adaptiveOrigin = store.useState('adaptiveOrigin');
+
+	const prevTriggerElementRef = React.useRef<Element | null>(null);
+
+	const runOnceAnimationsFinish = useAnimationsFinished(positionerElement);
+
+	const positioning = useAnchorPositioning({
+		anchor,
+		floatingRootContext,
+		positionMethod,
+		mounted,
+		side,
+		sideOffset,
+		align,
+		alignOffset,
+		arrowPadding,
+		collisionBoundary,
+		collisionPadding,
+		sticky,
+		disableAnchorTracking,
+		keepMounted,
+		nodeId,
+		collisionAvoidance,
+		adaptiveOrigin,
+	});
+
+	const domReference = floatingRootContext.useState('domReferenceElement');
+
+	// When the current trigger element changes, enable transitions on the
+	// positioner temporarily
+	useIsoLayoutEffect(() => {
+		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]);
+
+	const trueModalNonHover = modal === true && openReason !== REASONS.triggerHover;
+
+	useAnchoredPopupScrollLock(
+		open && trueModalNonHover,
+		openMethod === 'touch',
+		positionerElement,
+		triggerElement,
+	);
+
+	const setPositionerElement = store.useStateSetter('positionerElement');
+
+	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: [forwardedRef, setPositionerElement],
+		hidden: !mounted,
+		inert: !open,
+	});
+
+	return (
+		<PopoverPositionerContext.Provider value={positioning}>
+			{mounted && trueModalNonHover && (
+				<InternalBackdrop inert={inertValue(!open)} cutout={triggerElement} />
+			)}
+			<FloatingNode id={nodeId}>{element}</FloatingNode>
+		</PopoverPositionerContext.Provider>
+	);
+};
+
+export interface PopoverPositionerState {
+	/**
+	 * Whether the popover is currently open.
+	 */
+	open: boolean;
+	/**
+	 * The side of the anchor the component is placed on.
+	 */
+	side: Side;
+	/**
+	 * The alignment of the component relative to the anchor.
+	 */
+	align: Align;
+	/**
+	 * Whether the anchor element is hidden.
+	 */
+	anchorHidden: boolean;
+	/**
+	 * Whether CSS transitions should be disabled.
+	 */
+	instant: string | undefined;
+}
+
+export interface PopoverPositionerProps
+	extends
+		UseAnchorPositioningSharedParameters,
+		BaseUIComponentProps<'div', PopoverPositionerState> {}
+
+export namespace PopoverPositioner {
+	export type State = PopoverPositionerState;
+	export type Props = PopoverPositionerProps;
+}

package/src/popover/positioner/PopoverPositionerContext.ts

@@ -0,0 +1,28 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { Side, Align } from '../../internals/useAnchorPositioning';
+import type { FloatingContext } from '../../floating-ui-react';
+
+export interface PopoverPositionerContext {
+	side: Side;
+	align: Align;
+	arrowRef: React.RefObject<Element | null>;
+	arrowUncentered: boolean;
+	arrowStyles: React.CSSProperties;
+	context: FloatingContext;
+}
+
+export const PopoverPositionerContext = React.createContext<PopoverPositionerContext | undefined>(
+	undefined,
+);
+
+export function usePopoverPositionerContext() {
+	const context = React.useContext(PopoverPositionerContext);
+	if (!context) {
+		throw new Error(
+			'Base UI: PopoverPositionerContext is missing. PopoverPositioner parts must be placed within <Popover.Positioner>.',
+		);
+	}
+	return context;
+}

package/src/popover/positioner/PopoverPositionerCssVars.ts

@@ -0,0 +1,37 @@
+/**
+ * The available width between the trigger and the edge of the viewport.
+ * @type {number}
+ */
+export const availableWidth = '--available-width';
+/**
+ * The available height between the trigger and the edge of the viewport.
+ * @type {number}
+ */
+export const availableHeight = '--available-height';
+/**
+ * The anchor's width.
+ * @type {number}
+ */
+export const anchorWidth = '--anchor-width';
+/**
+ * The anchor's height.
+ * @type {number}
+ */
+export const anchorHeight = '--anchor-height';
+/**
+ * The coordinates that this element is anchored to. Used for animations and transitions.
+ * @type {string}
+ */
+export const transformOrigin = '--transform-origin';
+/**
+ * The width of the popover's positioner.
+ * It is important to set `width` to this value when using CSS to animate size changes.
+ * @type {number}
+ */
+export const positionerWidth = '--positioner-width';
+/**
+ * The height of the popover's positioner.
+ * It is important to set `height` to this value when using CSS to animate size changes.
+ * @type {number}
+ */
+export const positionerHeight = '--positioner-height';

package/src/popover/positioner/PopoverPositionerDataAttributes.ts

@@ -0,0 +1,24 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the popup is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the popup is closed.
+ */
+export const closed = CommonPopupDataAttributes.closed;
+/**
+ * Present when the anchor is hidden.
+ */
+export const anchorHidden = CommonPopupDataAttributes.anchorHidden;
+/**
+ * Indicates which side the popup is positioned relative to the trigger.
+ * @type {'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start'}
+ */
+export const side = CommonPopupDataAttributes.side;
+/**
+ * Indicates how the popup is aligned relative to specified side.
+ * @type {'start' | 'center' | 'end'}
+ */
+export const align = CommonPopupDataAttributes.align;