@octanejs/base-ui 0.1.50 → 0.1.52

package/src/utils/usePopupViewport.tsrx

@@ -0,0 +1,396 @@
+'use client';
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
+import { inertValue } from '@octanejs/base-ui-utils/inertValue';
+import { useAnimationFrame } from '@octanejs/base-ui-utils/useAnimationFrame';
+import { usePreviousValue } from '@octanejs/base-ui-utils/usePreviousValue';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { ownerDocument } from '@octanejs/base-ui-utils/owner';
+import type { ReactStore } from '@octanejs/base-ui-utils/store';
+import { useAnimationsFinished } from '../internals/useAnimationsFinished';
+import type { StateAttributesMapping } from '../internals/getStateAttributesProps';
+import { usePopupAutoResize } from './usePopupAutoResize';
+import type { Dimensions } from '../floating-ui-react/types';
+import type { Side } from '../internals/useAnchorPositioning';
+import { useDirection } from '../direction-provider';
+import { adaptiveOrigin } from './adaptiveOriginMiddleware';
+import * as CommonPopupCssVars from './CommonPopupCssVars';
+import * as CommonViewportDataAttributes from './CommonViewportDataAttributes';
+
+export const popupViewportStateMapping: StateAttributesMapping<{
+	activationDirection: string | undefined;
+}> = {
+	activationDirection: (value) =>
+		value
+			? {
+					[CommonViewportDataAttributes.activationDirection]: value,
+				}
+			: null,
+};
+
+export interface PopupViewportState {
+	/**
+	 * Direction from which the popup was activated, used for directional animations.
+	 */
+	activationDirection: string | undefined;
+	/**
+	 * Whether the viewport is currently transitioning between contents.
+	 */
+	transitioning: boolean;
+}
+
+type PopupViewportStore = Pick<ReactStore<any, any, any>, 'useState' | 'set'>;
+
+export interface UsePopupViewportParameters {
+	/**
+	 * Popup store instance for accessing shared popup state.
+	 */
+	store: PopupViewportStore;
+	/**
+	 * Side of the positioner relative to the trigger.
+	 */
+	side: Side;
+	/**
+	 * Viewport children to render in the current container.
+	 */
+	children?: React.OctaneNode;
+}
+
+export interface UsePopupViewportResult {
+	/**
+	 * The viewport children wrapped in current/previous containers as needed.
+	 */
+	children: React.OctaneNode;
+	/**
+	 * Viewport state used for data attributes and render prop styling.
+	 */
+	state: PopupViewportState;
+}
+
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Handles previous-content snapshots, auto-resize, and state attributes for transitions.
+ */
+export function usePopupViewport(parameters: UsePopupViewportParameters): UsePopupViewportResult {
+	const { store, side, children } = parameters;
+
+	const direction = useDirection();
+
+	const activeTrigger = store.useState('activeTriggerElement');
+	const activeTriggerId = store.useState('activeTriggerId');
+	const open = store.useState('open');
+	const payload = store.useState('payload');
+	const mounted = store.useState('mounted');
+	const popupElement = store.useState('popupElement');
+	const positionerElement = store.useState('positionerElement');
+
+	const previousActiveTrigger = usePreviousValue(open ? activeTrigger : null);
+	// Remount current content on trigger changes (and once more when payload lags) to avoid DOM reuse flashes.
+	// The key bumps immediately on trigger switches, then again if the payload arrives on a later render.
+	const currentContentKey = usePopupContentKey(activeTriggerId, payload);
+
+	const capturedNodeRef = React.useRef<HTMLElement | null>(null);
+	const [previousContentNode, setPreviousContentNode] = React.useState<HTMLElement | null>(null);
+
+	const [newTriggerOffset, setNewTriggerOffset] = React.useState<Offset | null>(null);
+
+	const currentContainerRef = React.useRef<HTMLDivElement | null>(null);
+	const previousContainerRef = React.useRef<HTMLDivElement | null>(null);
+
+	const onAnimationsFinished = useAnimationsFinished(currentContainerRef, true);
+	const cleanupFrame = useAnimationFrame();
+	const cleanupControllerRef = React.useRef<AbortController | null>(null);
+
+	const [previousContentDimensions, setPreviousContentDimensions] = React.useState<{
+		width: number;
+		height: number;
+	} | null>(null);
+
+	const [showStartingStyleAttribute, setShowStartingStyleAttribute] = React.useState(false);
+
+	useIsoLayoutEffect(() => {
+		store.set('adaptiveOrigin', adaptiveOrigin);
+		return () => {
+			store.set('adaptiveOrigin', undefined);
+		};
+	}, [store]);
+
+	const handleMeasureLayout = useStableCallback(() => {
+		currentContainerRef.current?.style.setProperty('animation', 'none');
+		currentContainerRef.current?.style.setProperty('transition', 'none');
+
+		previousContainerRef.current?.style.setProperty('display', 'none');
+	});
+
+	const handleMeasureLayoutComplete = useStableCallback((previousDimensions: Dimensions | null) => {
+		currentContainerRef.current?.style.removeProperty('animation');
+		currentContainerRef.current?.style.removeProperty('transition');
+
+		previousContainerRef.current?.style.removeProperty('display');
+
+		if (previousDimensions) {
+			setPreviousContentDimensions(previousDimensions);
+		}
+	});
+
+	const armViewportCleanup = useStableCallback(() => {
+		cleanupControllerRef.current?.abort();
+		const controller = new AbortController();
+		cleanupControllerRef.current = controller;
+		onAnimationsFinished(() => {
+			setPreviousContentNode(null);
+			setPreviousContentDimensions(null);
+			capturedNodeRef.current = null;
+		}, controller.signal);
+	});
+
+	const lastHandledTriggerRef = React.useRef<Element | null>(null);
+
+	useIsoLayoutEffect(() => {
+		if (!open || !mounted) {
+			lastHandledTriggerRef.current = null;
+		}
+	}, [open, mounted]);
+
+	useIsoLayoutEffect(() => {
+		// When a trigger changes, set the captured children HTML to state,
+		// so we can render both new and old content.
+		if (
+			activeTrigger &&
+			previousActiveTrigger &&
+			activeTrigger !== previousActiveTrigger &&
+			lastHandledTriggerRef.current !== activeTrigger &&
+			capturedNodeRef.current
+		) {
+			setPreviousContentNode(capturedNodeRef.current);
+			setShowStartingStyleAttribute(true);
+
+			// Calculate the relative position between the previous and new trigger,
+			// so we can pass it to the style hook for animation purposes.
+			const offset = calculateRelativePosition(previousActiveTrigger, activeTrigger);
+			setNewTriggerOffset(offset);
+
+			lastHandledTriggerRef.current = activeTrigger;
+		}
+	}, [activeTrigger, previousActiveTrigger]);
+
+	// Arm cleanup after a trigger change, and re-arm it if the current container remounts
+	// mid-transition when a lagging payload bumps `currentContentKey`. The remount discards
+	// the running entry animation (and with transition-style CSS the replacement mounts at
+	// final styles with no animation at all), so re-run the starting-style choreography —
+	// otherwise the watcher either strands or fires before the previous container's exit
+	// animation finishes.
+	useIsoLayoutEffect(() => {
+		if (previousContentNode == null) {
+			return;
+		}
+
+		// Abort the stale watcher synchronously. The remount cancels the old container's
+		// animations, and the resulting promise rejection would otherwise run the cleanup
+		// in a microtask before the re-armed watcher below is in place.
+		cleanupControllerRef.current?.abort();
+
+		setShowStartingStyleAttribute(true);
+
+		cleanupFrame.request(() => {
+			ReactDOM.flushSync(() => {
+				setShowStartingStyleAttribute(false);
+			});
+			armViewportCleanup();
+		});
+	}, [currentContentKey, previousContentNode, armViewportCleanup, cleanupFrame]);
+
+	// Capture a clone of the current content DOM subtree when not transitioning.
+	// We can't store previous React nodes as they may be stateful; instead we capture DOM clones for visual continuity.
+	useIsoLayoutEffect(() => {
+		// When a transition is in progress, we store the next content in capturedNodeRef.
+		// This handles the case where the trigger changes multiple times before the transition finishes.
+		// We want to always capture the latest content for the previous snapshot.
+		// So clicking quickly on T1, T2, T3 will result in the following sequence:
+		// 1. T1 -> T2: previousContent = T1, currentContent = T2
+		// 2. T2 -> T3: previousContent = T2, currentContent = T3
+		const source = currentContainerRef.current;
+		if (!source) {
+			return;
+		}
+
+		const wrapper = ownerDocument(source).createElement('div');
+		for (const child of Array.from(source.childNodes)) {
+			wrapper.appendChild(child.cloneNode(true));
+		}
+
+		capturedNodeRef.current = wrapper;
+	});
+
+	const isTransitioning = previousContentNode != null;
+	let childrenToRender: React.OctaneNode;
+	if (!isTransitioning) {
+		childrenToRender = (
+			<div data-current ref={currentContainerRef} key={currentContentKey}>
+				{children}
+			</div>
+		);
+	} else {
+		childrenToRender = (
+			<React.Fragment>
+				<div
+					data-previous
+					inert={inertValue(true)}
+					ref={previousContainerRef}
+					style={
+						{
+							...(previousContentDimensions
+								? {
+										[CommonPopupCssVars.popupWidth]: `${previousContentDimensions.width}px`,
+										[CommonPopupCssVars.popupHeight]: `${previousContentDimensions.height}px`,
+									}
+								: null),
+							position: 'absolute',
+						} as React.CSSProperties
+					}
+					key="previous"
+					data-ending-style={showStartingStyleAttribute ? undefined : ''}
+				/>
+				<div
+					data-current
+					ref={currentContainerRef}
+					key={currentContentKey}
+					data-starting-style={showStartingStyleAttribute ? '' : undefined}
+				>
+					{children}
+				</div>
+			</React.Fragment>
+		);
+	}
+
+	// When previousContentNode is present, imperatively populate the previous container with the cloned children.
+	useIsoLayoutEffect(() => {
+		const container = previousContainerRef.current;
+		if (!container || !previousContentNode) {
+			return;
+		}
+
+		container.replaceChildren(...Array.from(previousContentNode.childNodes));
+	}, [previousContentNode]);
+
+	usePopupAutoResize({
+		popupElement,
+		positionerElement,
+		mounted,
+		content: payload,
+		onMeasureLayout: handleMeasureLayout,
+		onMeasureLayoutComplete: handleMeasureLayoutComplete,
+		side,
+		direction,
+	});
+
+	const state: PopupViewportState = {
+		activationDirection: getActivationDirection(newTriggerOffset),
+		transitioning: isTransitioning,
+	};
+
+	return { children: childrenToRender, state };
+}
+
+type Offset = {
+	horizontal: number;
+	vertical: number;
+};
+
+/**
+ * Returns a string describing the provided offset.
+ * It describes both the horizontal and vertical offset, separated by a space.
+ *
+ * @param offset
+ */
+function getActivationDirection(offset: Offset | null): string | undefined {
+	if (!offset) {
+		return undefined;
+	}
+
+	return `${getValueWithTolerance(offset.horizontal, 5, 'right', 'left')} ${getValueWithTolerance(offset.vertical, 5, 'down', 'up')}`;
+}
+
+/**
+ * Returns a label describing the value (positive/negative) treating values
+ * within tolerance as zero.
+ *
+ * @param value Value to check
+ * @param tolerance Tolerance to treat the value as zero.
+ * @param positiveLabel
+ * @param negativeLabel
+ * @returns If 0 < abs(value) < tolerance, returns an empty string. Otherwise returns positiveLabel or negativeLabel.
+ */
+function getValueWithTolerance(
+	value: number,
+	tolerance: number,
+	positiveLabel: string,
+	negativeLabel: string,
+) {
+	if (value > tolerance) {
+		return positiveLabel;
+	}
+
+	if (value < -tolerance) {
+		return negativeLabel;
+	}
+
+	return '';
+}
+
+/**
+ * Calculates the relative position between centers of two elements.
+ */
+function calculateRelativePosition(from: Element, to: Element): Offset {
+	const fromRect = from.getBoundingClientRect();
+	const toRect = to.getBoundingClientRect();
+
+	const fromCenter = {
+		x: fromRect.left + fromRect.width / 2,
+		y: fromRect.top + fromRect.height / 2,
+	};
+	const toCenter = {
+		x: toRect.left + toRect.width / 2,
+		y: toRect.top + toRect.height / 2,
+	};
+
+	return {
+		horizontal: toCenter.x - fromCenter.x,
+		vertical: toCenter.y - fromCenter.y,
+	};
+}
+
+/**
+ * Returns a key that forces remounting content when triggers change or a payload is updated.
+ */
+function usePopupContentKey(activeTriggerId: string | null, payload: unknown): string {
+	const [contentKey, setContentKey] = React.useState(0);
+	const previousActiveTriggerIdRef = React.useRef(activeTriggerId);
+	const previousPayloadRef = React.useRef(payload);
+	const pendingPayloadUpdateRef = React.useRef(false);
+
+	useIsoLayoutEffect(() => {
+		// Compare against the last committed values to decide whether we need a new DOM subtree.
+		const previousActiveTriggerId = previousActiveTriggerIdRef.current;
+		const previousPayload = previousPayloadRef.current;
+		const triggerIdChanged = activeTriggerId !== previousActiveTriggerId;
+		const payloadChanged = payload !== previousPayload;
+
+		if (triggerIdChanged) {
+			// Remount immediately on trigger change; remember if payload hasn't caught up yet.
+			setContentKey((value) => value + 1);
+			pendingPayloadUpdateRef.current = !payloadChanged;
+		} else if (pendingPayloadUpdateRef.current && payloadChanged) {
+			// Payload arrived a render later, so remount once more to avoid reusing the old <img>.
+			setContentKey((value) => value + 1);
+			pendingPayloadUpdateRef.current = false;
+		}
+
+		// Persist current values for the next render's comparison.
+		previousActiveTriggerIdRef.current = activeTriggerId;
+		previousPayloadRef.current = payload;
+	}, [activeTriggerId, payload]);
+
+	return `${activeTriggerId ?? 'current'}-${contentKey}`;
+}

package/src/utils/usePositioner.tsrx

@@ -0,0 +1,50 @@
+import type * as React from 'octane';
+import type { WithBaseUIEvent } from '../internals/types';
+('use client');
+import { popupStateMapping } from './popupStateMapping';
+import {
+	useRenderElement,
+	type UseRenderElementComponentProps,
+} from '../internals/useRenderElement.tsrx';
+import { getDisabledMountTransitionStyles } from '../internals/getDisabledMountTransitionStyles';
+import type { TransitionStatus } from '../internals/useTransitionStatus';
+
+interface UsePositionerOptions {
+	styles: React.CSSProperties;
+	transitionStatus: TransitionStatus;
+	props?:
+		| WithBaseUIEvent<
+				Omit<React.ComponentProps<'div'>, 'style'> & { style?: React.CSSProperties | undefined }
+		  >
+		| undefined;
+	refs?: React.Ref<HTMLDivElement> | (React.Ref<HTMLDivElement> | undefined)[] | undefined;
+	hidden?: boolean | undefined;
+	inert?: boolean | undefined;
+}
+
+/**
+ * Renders the shared outer Positioner element used by popup components.
+ * Applies the common role, hidden state, transition styles, state attributes, and optional inert styling.
+ */
+export function usePositioner<State extends Record<string, any>>(
+	componentProps: UseRenderElementComponentProps<State>,
+	state: State,
+	{ styles, transitionStatus, props, refs, hidden, inert = false }: UsePositionerOptions,
+) {
+	const style: React.CSSProperties = { ...styles };
+
+	if (inert) {
+		style.pointerEvents = 'none';
+	}
+
+	return useRenderElement('div', componentProps, {
+		state,
+		ref: refs,
+		props: [
+			{ role: 'presentation', hidden, style },
+			getDisabledMountTransitionStyles(transitionStatus),
+			props,
+		],
+		stateAttributesMapping: popupStateMapping,
+	});
+}

package/src/utils/useRegisteredLabelId.ts

@@ -1,32 +1,21 @@
-// Ported from .base-ui/packages/react/src/utils/useRegisteredLabelId.ts. Generates a
-// stable id (via useBaseUiId) and registers it with the owning Root through a layout
-// effect (`setLabelId(id)`; cleared on unmount) — the Root reflects it as
-// `aria-labelledby`. Shared by Meter.Label / Progress.Label.
-//
-// SLOT: plain-`.ts` hook; the trailing arg is the caller's slot.
-import { useLayoutEffect } from 'octane';
+/** @jsxImportSource octane */
+'use client';
+import type * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useBaseUiId } from '../internals/useBaseUiId';
 
-import { S, splitSlot, subSlot } from '../internal';
-import { useBaseUiId } from './useBaseUiId';
+export function useRegisteredLabelId(
+	idProp: string | undefined,
+	setLabelId: React.Dispatch<React.SetStateAction<string | undefined>>,
+): string | undefined {
+	const id = useBaseUiId(idProp);
 
-export function useRegisteredLabelId(...args: any[]): string | undefined {
-	const [user, slotArg] = splitSlot(args);
-	const slot = slotArg ?? S('useRegisteredLabelId');
-	const idProp = user[0] as string | undefined;
-	const setLabelId = user[1] as (id: string | undefined) => void;
-
-	const id = useBaseUiId(idProp, subSlot(slot, 'id'));
-
-	useLayoutEffect(
-		() => {
-			setLabelId(id);
-			return () => {
-				setLabelId(undefined);
-			};
-		},
-		[id, setLabelId],
-		subSlot(slot, 'e:label'),
-	);
+	useIsoLayoutEffect(() => {
+		setLabelId(id);
+		return () => {
+			setLabelId((currentId) => (currentId === id ? undefined : currentId));
+		};
+	}, [id, setLabelId]);
 
 	return id;
 }