@octanejs/base-ui 0.1.50 → 0.1.51

package/src/tooltip/portal/TooltipPortal.tsrx

@@ -0,0 +1,54 @@
+'use client';
+import * as React from 'octane';
+import { useTooltipRootContext } from '../root/TooltipRootContext';
+import { TooltipPortalContext } from './TooltipPortalContext';
+import { FloatingPortalLite } from '../../utils/FloatingPortalLite.tsrx';
+import { type BaseUIComponentProps } from '../../internals/types';
+
+/**
+ * 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 Tooltip](https://base-ui.com/react/components/tooltip)
+ */
+export const TooltipPortal = function TooltipPortal(
+	propsWithRef: React.PropsWithoutRef<TooltipPortal.Props> & { ref?: React.Ref<HTMLDivElement> },
+) {
+	const { ref: forwardedRef = null, ...props } = propsWithRef;
+	const { keepMounted = false, ...portalProps } = props;
+
+	const store = useTooltipRootContext();
+	const mounted = store.useState('mounted');
+
+	const shouldRender = mounted || keepMounted;
+	if (!shouldRender) {
+		return null;
+	}
+
+	return (
+		<TooltipPortalContext.Provider value={keepMounted}>
+			<FloatingPortalLite ref={forwardedRef} {...portalProps} />
+		</TooltipPortalContext.Provider>
+	);
+};
+
+export interface TooltipPortalState {}
+
+export interface TooltipPortalProps extends BaseUIComponentProps<'div', TooltipPortalState> {
+	/**
+	 * 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 TooltipPortal {
+	export type State = TooltipPortalState;
+	export type Props = TooltipPortalProps;
+}

package/src/tooltip/portal/TooltipPortalContext.ts

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

package/src/tooltip/positioner/TooltipPositioner.tsrx

@@ -0,0 +1,150 @@
+'use client';
+import * as React from 'octane';
+import { useTooltipRootContext } from '../root/TooltipRootContext';
+import { TooltipPositionerContext } from './TooltipPositionerContext';
+import {
+	useAnchorPositioning,
+	type Side,
+	type Align,
+	type UseAnchorPositioningSharedParameters,
+} from '../../internals/useAnchorPositioning';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { useTooltipPortalContext } from '../portal/TooltipPortalContext';
+import { POPUP_COLLISION_AVOIDANCE } from '../../internals/constants';
+import { usePositioner } from '../../utils/usePositioner.tsrx';
+
+/**
+ * Positions the tooltip against the trigger.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Tooltip](https://base-ui.com/react/components/tooltip)
+ */
+export const TooltipPositioner = function TooltipPositioner(
+	componentPropsWithRef: React.PropsWithoutRef<TooltipPositioner.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const {
+		render,
+		className,
+		anchor,
+		positionMethod = 'absolute',
+		side = 'top',
+		align = 'center',
+		sideOffset = 0,
+		alignOffset = 0,
+		collisionBoundary = 'clipping-ancestors',
+		collisionPadding = 5,
+		arrowPadding = 5,
+		sticky = false,
+		disableAnchorTracking = false,
+		collisionAvoidance = POPUP_COLLISION_AVOIDANCE,
+		style,
+		...elementProps
+	} = componentProps;
+
+	const store = useTooltipRootContext();
+	const keepMounted = useTooltipPortalContext();
+
+	const open = store.useState('open');
+	const mounted = store.useState('mounted');
+	const trackCursorAxis = store.useState('trackCursorAxis');
+	const disableHoverablePopup = store.useState('disableHoverablePopup');
+	const floatingRootContext = store.useState('floatingRootContext');
+	const instantType = store.useState('instantType');
+	const transitionStatus = store.useState('transitionStatus');
+	const adaptiveOrigin = store.useState('adaptiveOrigin');
+
+	const positioning = useAnchorPositioning({
+		anchor,
+		positionMethod,
+		floatingRootContext,
+		mounted,
+		side,
+		sideOffset,
+		align,
+		alignOffset,
+		collisionBoundary,
+		collisionPadding,
+		sticky,
+		arrowPadding,
+		disableAnchorTracking,
+		keepMounted,
+		collisionAvoidance,
+		adaptiveOrigin,
+	});
+
+	const state: TooltipPositionerState = React.useMemo(
+		() => ({
+			open,
+			side: positioning.side,
+			align: positioning.align,
+			anchorHidden: positioning.anchorHidden,
+			instant: trackCursorAxis !== 'none' ? 'tracking-cursor' : instantType,
+		}),
+		[
+			open,
+			positioning.side,
+			positioning.align,
+			positioning.anchorHidden,
+			trackCursorAxis,
+			instantType,
+		],
+	);
+
+	const element = usePositioner(componentProps, state, {
+		styles: positioning.positionerStyles,
+		transitionStatus,
+		props: elementProps,
+		refs: [forwardedRef, store.useStateSetter('positionerElement')],
+		hidden: !mounted,
+		inert: !open || trackCursorAxis === 'both' || disableHoverablePopup,
+	});
+
+	return (
+		<TooltipPositionerContext.Provider value={positioning}>
+			{element}
+		</TooltipPositionerContext.Provider>
+	);
+};
+
+export interface TooltipPositionerState {
+	/**
+	 * Whether the tooltip 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 TooltipPositionerProps
+	extends
+		BaseUIComponentProps<'div', TooltipPositionerState>,
+		Omit<UseAnchorPositioningSharedParameters, 'side'> {
+	/**
+	 * Which side of the anchor element to align the popup against.
+	 * May automatically change to avoid collisions.
+	 * @default 'top'
+	 */
+	side?: Side | undefined;
+}
+
+export namespace TooltipPositioner {
+	export type State = TooltipPositionerState;
+	export type Props = TooltipPositionerProps;
+}

package/src/tooltip/positioner/TooltipPositionerContext.ts

@@ -0,0 +1,23 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import type { UseAnchorPositioningReturnValue } from '../../internals/useAnchorPositioning';
+
+export type TooltipPositionerContext = Pick<
+	UseAnchorPositioningReturnValue,
+	'side' | 'align' | 'arrowRef' | 'arrowUncentered' | 'arrowStyles'
+>;
+
+export const TooltipPositionerContext = React.createContext<TooltipPositionerContext | undefined>(
+	undefined,
+);
+
+export function useTooltipPositionerContext() {
+	const context = React.useContext(TooltipPositionerContext);
+	if (context === undefined) {
+		throw new Error(
+			'Base UI: TooltipPositionerContext is missing. TooltipPositioner parts must be placed within <Tooltip.Positioner>.',
+		);
+	}
+	return context;
+}

package/src/tooltip/positioner/TooltipPositionerCssVars.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 tooltip'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 tooltip'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/tooltip/positioner/TooltipPositionerDataAttributes.ts

@@ -0,0 +1,24 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the tooltip is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the tooltip 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;

package/src/tooltip/provider/TooltipProvider.tsrx

@@ -0,0 +1,49 @@
+'use client';
+import * as React from 'octane';
+import { FloatingDelayGroup } from '../../floating-ui-react';
+import { TooltipProviderContext } from './TooltipProviderContext';
+
+/**
+ * Provides a shared delay for multiple tooltips. The grouping logic ensures that
+ * once a tooltip becomes visible, the adjacent tooltips will be shown instantly.
+ *
+ * Documentation: [Base UI Tooltip](https://base-ui.com/react/components/tooltip)
+ */
+export const TooltipProvider: React.FC<TooltipProvider.Props> = function TooltipProvider(props) {
+	const { delay, closeDelay, timeout = 400 } = props;
+
+	const delayValue = React.useMemo(() => ({ open: delay, close: closeDelay }), [delay, closeDelay]);
+
+	return (
+		<TooltipProviderContext.Provider value={delay}>
+			<FloatingDelayGroup delay={delayValue} timeoutMs={timeout}>
+				{props.children}
+			</FloatingDelayGroup>
+		</TooltipProviderContext.Provider>
+	);
+};
+
+export interface TooltipProviderState {}
+
+export interface TooltipProviderProps {
+	children?: React.OctaneNode;
+	/**
+	 * How long to wait before opening the tooltip on hover. Specified in milliseconds.
+	 */
+	delay?: number | undefined;
+	/**
+	 * How long to wait before closing a tooltip. Specified in milliseconds.
+	 */
+	closeDelay?: number | undefined;
+	/**
+	 * Another tooltip will open instantly if the previous tooltip
+	 * is closed within this timeout. Specified in milliseconds.
+	 * @default 400
+	 */
+	timeout?: number | undefined;
+}
+
+export namespace TooltipProvider {
+	export type State = TooltipProviderState;
+	export type Props = TooltipProviderProps;
+}

package/src/tooltip/provider/TooltipProviderContext.ts

@@ -0,0 +1,12 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+
+/**
+ * Holds the provider's `delay` value. `closeDelay` is handled by the delay group.
+ */
+export const TooltipProviderContext = React.createContext<number | undefined>(undefined);
+
+export function useTooltipProviderContext(): number | undefined {
+	return React.useContext(TooltipProviderContext);
+}

package/src/tooltip/root/TooltipRoot.tsrx

@@ -0,0 +1,282 @@
+'use client';
+import * as React from 'octane';
+import { fastComponent } from '@octanejs/base-ui-utils/fastHooks';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { TooltipRootContext } from './TooltipRootContext';
+import { useClientPoint, useDismiss } from '../../floating-ui-react';
+import {
+	type BaseUIChangeEventDetails,
+	createChangeEventDetails,
+} from '../../internals/createBaseUIEventDetails';
+import {
+	PopupHandleAttachment,
+	useImplicitActiveTrigger,
+	usePopupRootStore,
+	useOpenStateTransitions,
+	usePopupInteractionProps,
+	type PayloadChildRenderFunction,
+} from '../../utils/popups';
+import { mergeProps } from '../../merge-props';
+import { TooltipStore, type State as TooltipStoreState } from '../store/TooltipStore';
+import { type TooltipHandle } from '../store/TooltipHandle';
+import { REASONS } from '../../internals/reasons';
+
+/**
+ * Groups all parts of the tooltip.
+ * Doesn't render its own HTML element.
+ *
+ * Documentation: [Base UI Tooltip](https://base-ui.com/react/components/tooltip)
+ */
+export const TooltipRoot = fastComponent(function TooltipRoot<Payload>(
+	props: TooltipRoot.Props<Payload>,
+) {
+	const {
+		disabled = false,
+		defaultOpen = false,
+		open: openProp,
+		disableHoverablePopup = false,
+		trackCursorAxis = 'none',
+		actionsRef,
+		onOpenChange,
+		onOpenChangeComplete,
+		handle,
+		triggerId: triggerIdProp,
+		defaultTriggerId: defaultTriggerIdProp = null,
+		children,
+	} = props;
+
+	const store = usePopupRootStore(
+		(floatingId, nested) =>
+			new TooltipStore<Payload>(
+				{
+					open: defaultOpen,
+					openProp,
+					activeTriggerId: defaultTriggerIdProp,
+					triggerIdProp,
+				},
+				floatingId,
+				nested,
+			),
+	);
+
+	store.useControlledProp('openProp', openProp);
+	store.useControlledProp('triggerIdProp', triggerIdProp);
+
+	store.useContextCallback('onOpenChange', onOpenChange);
+	store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
+
+	const openState = store.useState('open');
+	const open = !disabled && openState;
+
+	const activeTriggerId = store.useState('activeTriggerId');
+	const mounted = store.useState('mounted');
+	const payload = store.useState('payload') as Payload | undefined;
+
+	store.useSyncedValues({
+		trackCursorAxis,
+		disableHoverablePopup,
+		disabled,
+	});
+
+	useImplicitActiveTrigger(store, { closeOnActiveTriggerUnmount: true });
+	const { forceUnmount, transitionStatus } = useOpenStateTransitions(open, store);
+	const isInstantPhase = store.useState('isInstantPhase');
+	const instantType = store.useState('instantType');
+	const lastOpenChangeReason = store.useState('lastOpenChangeReason');
+
+	// Animations should be instant in two cases:
+	// 1) Opening during the provider's instant phase (adjacent tooltip opens instantly)
+	// 2) Closing because another tooltip opened (reason === 'none')
+	// Otherwise, allow the animation to play. In particular, do not disable animations
+	// during the 'ending' phase unless it's due to a sibling opening.
+	const previousInstantTypeRef = React.useRef<TooltipStoreState<Payload>['instantType'] | null>(
+		null,
+	);
+
+	useIsoLayoutEffect(() => {
+		if (openState && disabled) {
+			store.setOpen(false, createChangeEventDetails(REASONS.disabled));
+		}
+	}, [openState, disabled, store]);
+
+	useIsoLayoutEffect(() => {
+		if (
+			(transitionStatus === 'ending' && lastOpenChangeReason === REASONS.none) ||
+			(transitionStatus !== 'ending' && isInstantPhase)
+		) {
+			// Capture the current instant type so we can restore it later
+			// and set to 'delay' to disable animations while moving from one trigger to another
+			// within a delay group.
+			if (instantType !== 'delay') {
+				previousInstantTypeRef.current = instantType;
+			}
+			store.set('instantType', 'delay');
+		} else if (previousInstantTypeRef.current !== null) {
+			store.set('instantType', previousInstantTypeRef.current);
+			previousInstantTypeRef.current = null;
+		}
+	}, [transitionStatus, isInstantPhase, lastOpenChangeReason, instantType, store]);
+
+	useIsoLayoutEffect(() => {
+		if (open) {
+			if (activeTriggerId == null) {
+				store.set('payload', undefined);
+			}
+		}
+	}, [store, activeTriggerId, open]);
+
+	React.useImperativeHandle(
+		actionsRef,
+		() => ({
+			unmount: forceUnmount,
+			close: () => store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction)),
+		}),
+		[forceUnmount, store],
+	);
+
+	const shouldRenderInteractions = open || mounted || (!disabled && trackCursorAxis !== 'none');
+
+	return (
+		<TooltipRootContext.Provider value={store as TooltipRootContext}>
+			{handle && <PopupHandleAttachment handle={handle} store={store} />}
+			{shouldRenderInteractions && (
+				<TooltipInteractions store={store} disabled={disabled} trackCursorAxis={trackCursorAxis} />
+			)}
+			{typeof children === 'function' && !React.isChildrenBlock(children)
+				? children({ payload })
+				: children}
+		</TooltipRootContext.Provider>
+	);
+});
+
+export interface TooltipRootState {}
+
+export interface TooltipRootProps<Payload = unknown> {
+	/**
+	 * Whether the tooltip is initially open.
+	 *
+	 * To render a controlled tooltip, use the `open` prop instead.
+	 * @default false
+	 */
+	defaultOpen?: boolean | undefined;
+	/**
+	 * Whether the tooltip is currently open.
+	 */
+	open?: boolean | undefined;
+	/**
+	 * Event handler called when the tooltip is opened or closed.
+	 */
+	onOpenChange?:
+		((open: boolean, eventDetails: TooltipRoot.ChangeEventDetails) => void) | undefined;
+	/**
+	 * Event handler called after any animations complete when the tooltip is opened or closed.
+	 */
+	onOpenChangeComplete?: ((open: boolean) => void) | undefined;
+	/**
+	 * Whether the tooltip contents can be hovered without closing the tooltip.
+	 * @default false
+	 */
+	disableHoverablePopup?: boolean | undefined;
+	/**
+	 * Determines which axis the tooltip should track the cursor on.
+	 * @default 'none'
+	 */
+	trackCursorAxis?: 'none' | 'x' | 'y' | 'both' | undefined;
+	/**
+	 * A ref to imperative actions.
+	 * - `unmount`: Unmounts the tooltip popup.
+	 * - `close`: Closes the tooltip imperatively when called.
+	 */
+	actionsRef?: React.RefObject<TooltipRoot.Actions | null> | undefined;
+	/**
+	 * Whether the tooltip is disabled.
+	 * @default false
+	 */
+	disabled?: boolean | undefined;
+	/**
+	 * A handle to associate the tooltip with a trigger.
+	 * If specified, allows external triggers to control the tooltip's open state.
+	 * Can be created with the Tooltip.createHandle() method.
+	 */
+	handle?: TooltipHandle<Payload> | undefined;
+	/**
+	 * The content of the tooltip.
+	 * 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>;
+	/**
+	 * ID of the trigger that the tooltip is associated with.
+	 * This is useful in conjunction with the `open` prop to create a controlled tooltip.
+	 * There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
+	 */
+	triggerId?: string | null | undefined;
+	/**
+	 * ID of the trigger that the tooltip is associated with.
+	 * This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
+	 */
+	defaultTriggerId?: string | null | undefined;
+}
+
+export interface TooltipRootActions {
+	unmount: () => void;
+	close: () => void;
+}
+
+export type TooltipRootChangeEventReason =
+	| typeof REASONS.triggerHover
+	| typeof REASONS.triggerFocus
+	| typeof REASONS.triggerPress
+	| typeof REASONS.outsidePress
+	| typeof REASONS.escapeKey
+	| typeof REASONS.disabled
+	| typeof REASONS.imperativeAction
+	| typeof REASONS.none;
+
+export type TooltipRootChangeEventDetails =
+	BaseUIChangeEventDetails<TooltipRoot.ChangeEventReason> & {
+		preventUnmountOnClose(): void;
+	};
+
+export namespace TooltipRoot {
+	export type State = TooltipRootState;
+	export type Props<Payload = unknown> = TooltipRootProps<Payload>;
+	export type Actions = TooltipRootActions;
+	export type ChangeEventReason = TooltipRootChangeEventReason;
+	export type ChangeEventDetails = TooltipRootChangeEventDetails;
+}
+
+function TooltipInteractions<Payload>({
+	store,
+	disabled,
+	trackCursorAxis,
+}: {
+	store: TooltipStore<Payload>;
+	disabled: boolean;
+	trackCursorAxis: 'none' | 'x' | 'y' | 'both';
+}) {
+	const floatingRootContext = store.useState('floatingRootContext');
+
+	const dismiss = useDismiss(floatingRootContext, {
+		enabled: !disabled,
+		referencePress: () => store.select('closeOnClick'),
+	});
+	const clientPoint = useClientPoint(floatingRootContext, {
+		enabled: !disabled && trackCursorAxis !== 'none',
+		axis: trackCursorAxis === 'none' ? undefined : trackCursorAxis,
+	});
+
+	// Both hooks return `trigger: reference` (same object identity), so the active and
+	// inactive trigger props can never differ. `useClientPoint` has no floating-side props.
+	const triggerProps = React.useMemo(
+		() => mergeProps(clientPoint.reference, dismiss.reference),
+		[clientPoint.reference, dismiss.reference],
+	);
+	usePopupInteractionProps(store, {
+		activeTriggerProps: triggerProps,
+		inactiveTriggerProps: triggerProps,
+		popupProps: dismiss.floating ?? EMPTY_OBJECT,
+	});
+
+	return null;
+}

package/src/tooltip/root/TooltipRootContext.ts

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