@octanejs/base-ui 0.1.50 → 0.1.51

package/src/internals/useRenderElement.tsrx

@@ -0,0 +1,284 @@
+import * as React from 'octane';
+import { useMergedRefs, useMergedRefsN } from '@octanejs/base-ui-utils/useMergedRefs';
+import { getReactElementRef } from '@octanejs/base-ui-utils/getReactElementRef';
+import { mergeObjects } from '@octanejs/base-ui-utils/mergeObjects';
+import { warn } from '@octanejs/base-ui-utils/warn';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import type { BaseUIComponentProps, ComponentRenderFn, HTMLProps, WithBaseUIEvent } from './types';
+import { getStateAttributesProps, type StateAttributesMapping } from './getStateAttributesProps';
+import { resolveClassName } from '../utils/resolveClassName';
+import { resolveStyle } from '../utils/resolveStyle';
+import { mergeStyles } from '../utils/mergeStyles';
+import { mergeProps, mergePropsN, mergeClassNames } from '../merge-props';
+
+type IntrinsicTagName = keyof React.JSX.IntrinsicElements;
+
+/**
+ * Renders a Base UI element.
+ *
+ * @param element The default HTML element to render. Can be overridden by the `render` prop.
+ * @param componentProps An object containing the `render` and `className` props to be used for element customization. Other props are ignored.
+ * @param params Additional parameters for rendering the element.
+ */
+export function useRenderElement<
+	State extends Record<string, any>,
+	RenderedElementType extends Element,
+	TagName extends IntrinsicTagName | undefined,
+	Enabled extends boolean | undefined = undefined,
+>(
+	element: TagName,
+	componentProps: UseRenderElementComponentProps<State>,
+	params: UseRenderElementParameters<State, RenderedElementType, TagName, Enabled> = {},
+): Enabled extends false ? null : React.ReactElement {
+	const renderProp = componentProps.render;
+
+	const outProps = useRenderElementProps(componentProps, params, renderProp);
+
+	if (params.enabled === false) {
+		return null as Enabled extends false ? null : React.ReactElement;
+	}
+
+	const state = params.state ?? (EMPTY_OBJECT as State);
+	return evaluateRenderProp(element, renderProp, outProps, state) as Enabled extends false
+		? null
+		: React.ReactElement;
+}
+
+/**
+ * Computes render element final props.
+ */
+function useRenderElementProps<
+	State extends Record<string, any>,
+	RenderedElementType extends Element,
+	TagName extends IntrinsicTagName | undefined,
+	Enabled extends boolean | undefined,
+>(
+	componentProps: UseRenderElementComponentProps<State>,
+	params: UseRenderElementParameters<State, RenderedElementType, TagName, Enabled>,
+	renderProp: UseRenderElementComponentProps<State>['render'],
+): HTMLProps {
+	// OCTANE DIVERGENCE[ref-as-prop-class-composition][differential:base-ui-render-element]: compose native element props and refs.
+	const { className: classNameProp, style: styleProp } = componentProps;
+
+	const {
+		state = EMPTY_OBJECT as State,
+		ref,
+		props,
+		stateAttributesMapping,
+		enabled = true,
+	} = params;
+
+	const className = enabled ? resolveClassName(classNameProp, state) : undefined;
+	const style = enabled ? resolveStyle(styleProp, state) : undefined;
+
+	const stateProps = enabled
+		? getStateAttributesProps(state, stateAttributesMapping)
+		: EMPTY_OBJECT;
+
+	const resolvedProps = enabled && props ? resolveRenderFunctionProps<TagName>(props) : undefined;
+
+	// Ensure outProps is always a new mutable object when enabled, never EMPTY_OBJECT.
+	// This prevents potential TypeError when setting ref, className, or style properties,
+	// since EMPTY_OBJECT is frozen and mutations would fail in strict mode.
+	const outProps: HTMLProps = enabled
+		? (mergeObjects(stateProps, resolvedProps) ?? {})
+		: EMPTY_OBJECT;
+
+	// SAFETY: The `useMergedRefs` functions use a single hook to store the same value,
+	// switching between them at runtime is safe. If this assertion fails, React will
+	// throw at runtime anyway.
+	// This also skips the `useMergedRefs` call on the server, which is fine because
+	// refs are not used on the server side.
+	/* eslint-disable react-hooks/rules-of-hooks */
+	if (typeof document !== 'undefined') {
+		if (!enabled) {
+			// Called only to keep the hook order stable when disabled; the merged ref is unused.
+			void useMergedRefs(null, null);
+		} else if (Array.isArray(ref)) {
+			outProps.ref = useMergedRefsN([outProps.ref, getReactElementRef(renderProp), ...ref]);
+		} else {
+			outProps.ref = useMergedRefs(outProps.ref, getReactElementRef(renderProp), ref);
+		}
+	}
+
+	if (!enabled) {
+		return EMPTY_OBJECT;
+	}
+
+	if (className !== undefined) {
+		outProps.className = mergeClassNames(React.normalizeClass(outProps.className), className);
+	}
+
+	if (style !== undefined) {
+		outProps.style = mergeStyles(outProps.style, style);
+	}
+
+	return outProps;
+}
+
+function resolveRenderFunctionProps<TagName extends IntrinsicTagName | undefined>(
+	props: NonNullable<UseRenderElementParameters<any, any, TagName, any>['props']>,
+): RenderFunctionProps<TagName> {
+	if (Array.isArray(props)) {
+		return mergePropsN(props) as RenderFunctionProps<TagName>;
+	}
+
+	return mergeProps(undefined, props) as RenderFunctionProps<TagName>;
+}
+
+const COMPONENT_IDENTIFIER_PATTERN = /^[A-Z][A-Za-z0-9$]*$/;
+const LOWERCASE_CHARACTER_PATTERN = /[a-z]/;
+
+function evaluateRenderProp<T extends React.ElementType, S>(
+	element: IntrinsicTagName | undefined,
+	render: BaseUIComponentProps<T, S>['render'],
+	props: HTMLProps,
+	state: S,
+): React.ReactElement {
+	if (render) {
+		if (typeof render === 'function') {
+			if (process.env.NODE_ENV !== 'production') {
+				warnIfRenderPropLooksLikeComponent(render);
+			}
+			return render(props, state);
+		}
+
+		const mergedProps = mergeProps(props, render.props);
+
+		mergedProps.ref = props.ref;
+
+		// There is a high number of indirections, the error message thrown by React.cloneElement() is
+		// hard to use for developers, this logic provides a better context.
+		//
+		// Our general guideline is to never change the control flow depending on the environment.
+		// However, React.cloneElement() throws if React.isValidElement() is false,
+		// so we can throw before with custom message.
+		if (process.env.NODE_ENV !== 'production') {
+			if (!React.isValidElement(render)) {
+				// TODO: fix mui/no-guarded-throw
+				// eslint-disable-next-line mui/no-guarded-throw
+				throw new Error(
+					[
+						'Base UI: The `render` prop was provided an invalid React element as `React.isValidElement(render)` is `false`.',
+						'A valid React element must be provided to the `render` prop because it is cloned with props to replace the default element.',
+						'https://base-ui.com/r/invalid-render-prop',
+					].join('\n'),
+				);
+			}
+		}
+
+		return React.cloneElement(render, mergedProps);
+	}
+	if (element) {
+		if (typeof element === 'string') {
+			return renderTag(element, props);
+		}
+	}
+	// Unreachable, but the typings on `useRenderElement` need to be reworked
+	// to annotate it correctly.
+	throw new Error('Base UI: Render element or function are not defined.');
+}
+
+function warnIfRenderPropLooksLikeComponent(renderFn: { name: string }) {
+	const functionName = renderFn.name;
+	if (functionName.length === 0) {
+		return;
+	}
+
+	if (!COMPONENT_IDENTIFIER_PATTERN.test(functionName)) {
+		return;
+	}
+
+	if (!LOWERCASE_CHARACTER_PATTERN.test(functionName)) {
+		return;
+	}
+
+	warn(
+		`The \`render\` prop received a function named \`${functionName}\` that starts with an uppercase letter.`,
+		'This usually means a React component was passed directly as `render={Component}`.',
+		'Base UI calls `render` as a plain function, which can break the Rules of Hooks during reconciliation.',
+		'If this is an intentional render callback, rename it to start with a lowercase letter.',
+		'Use `render={<Component />}` or `render={(props) => <Component {...props} />}` instead.',
+		'https://base-ui.com/r/invalid-render-prop',
+	);
+}
+
+function renderTag(Tag: string, props: Record<string, any>) {
+	if (Tag === 'button') {
+		return <button type="button" {...props} key={props.key} />;
+	}
+	if (Tag === 'img') {
+		return <img alt="" {...props} key={props.key} />;
+	}
+	return React.createElement(Tag, props);
+}
+
+type RenderFunctionProps<TagName> = TagName extends keyof React.JSX.IntrinsicElements
+	? Omit<React.JSX.IntrinsicElements[TagName], 'ref' | 'style'> & {
+			ref?: React.Ref<Element>;
+			style?: React.CSSProperties | undefined;
+		}
+	: HTMLProps;
+
+export type UseRenderElementParameters<
+	State,
+	RenderedElementType extends Element,
+	TagName,
+	Enabled extends boolean | undefined,
+> = {
+	/**
+	 * If `false`, the hook will skip most of its internal logic and return `null`.
+	 * This is useful for rendering a component conditionally.
+	 * @default true
+	 */
+	enabled?: Enabled | undefined;
+	/**
+	 * @deprecated
+	 */
+	propGetter?: ((externalProps: HTMLProps) => HTMLProps) | undefined;
+	/**
+	 * The ref to apply to the rendered element.
+	 */
+	ref?: React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[] | undefined;
+	/**
+	 * The state of the component.
+	 */
+	state?: State | undefined;
+	/**
+	 * Intrinsic props to be spread on the rendered element.
+	 */
+	props?:
+		| WithBaseUIEvent<RenderFunctionProps<TagName>>
+		| Array<
+				| WithBaseUIEvent<RenderFunctionProps<TagName>>
+				| undefined
+				| ((props: RenderFunctionProps<TagName>) => RenderFunctionProps<TagName>)
+		  >
+		| undefined;
+	/**
+	 * A mapping of state to `data-*` attributes.
+	 */
+	stateAttributesMapping?: StateAttributesMapping<State> | undefined;
+};
+
+export interface UseRenderElementComponentProps<State> {
+	/**
+	 * The class name to apply to the rendered element.
+	 * Can be a string or a function that accepts the state and returns a string.
+	 */
+	className?: string | ((state: State) => string | undefined) | undefined;
+	/**
+	 * The render prop or React element to override the default element.
+	 */
+	render?: undefined | React.ReactElement | ComponentRenderFn<Omit<HTMLProps, 'ref'>, State>;
+	/**
+	 * The style to apply to the rendered element.
+	 * Can be a style object or a function that accepts the state and returns a style object.
+	 */
+	style?: React.CSSProperties | ((state: State) => React.CSSProperties | undefined) | undefined;
+}
+
+export interface UseRenderElementState {}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/internals/useTransitionStatus.ts

@@ -0,0 +1,98 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { AnimationFrame } from '@octanejs/base-ui-utils/useAnimationFrame';
+
+export type TransitionStatus = 'starting' | 'ending' | 'idle' | undefined;
+
+/**
+ * Provides a status string for CSS animations.
+ * @param open - a boolean that determines if the element is open.
+ * @param enableIdleState - a boolean that enables the `'idle'` state between `'starting'` and `'ending'`
+ * @param deferEndingState - a boolean that delays the `'ending'` state by a frame
+ * @param animateInitialOpen - a boolean that makes an element which mounts already open still go
+ *   through `'starting'`. Off by default so content that was open on the first render (a
+ *   `defaultOpen` popup on page load, SSR'd markup) doesn't animate in.
+ */
+export function useTransitionStatus(
+	open: boolean,
+	enableIdleState: boolean = false,
+	deferEndingState: boolean = false,
+	animateInitialOpen: boolean = false,
+) {
+	const [transitionStatus, setTransitionStatus] = React.useState<TransitionStatus>(
+		open && enableIdleState ? 'idle' : undefined,
+	);
+	// Starting at `false` while open lets the `open && !mounted` branch below run on the first
+	// render, which is what produces the `'starting'` phase. React re-renders before committing, so
+	// the element is still mounted in the same pass.
+	const [mounted, setMounted] = React.useState(open && !animateInitialOpen);
+
+	if (open && !mounted) {
+		setMounted(true);
+		setTransitionStatus('starting');
+	}
+
+	if (!open && mounted && transitionStatus !== 'ending' && !deferEndingState) {
+		setTransitionStatus('ending');
+	}
+
+	if (!open && !mounted && transitionStatus === 'ending') {
+		setTransitionStatus(undefined);
+	}
+
+	useIsoLayoutEffect(() => {
+		if (!open && mounted && transitionStatus !== 'ending' && deferEndingState) {
+			const frame = AnimationFrame.request(() => {
+				setTransitionStatus('ending');
+			});
+
+			return () => {
+				AnimationFrame.cancel(frame);
+			};
+		}
+
+		return undefined;
+	}, [open, mounted, transitionStatus, deferEndingState]);
+
+	useIsoLayoutEffect(() => {
+		if (!open || enableIdleState) {
+			return undefined;
+		}
+
+		const frame = AnimationFrame.request(() => {
+			// Avoid `flushSync` here due to Firefox.
+			// See https://github.com/mui/base-ui/pull/3424
+			setTransitionStatus(undefined);
+		});
+
+		return () => {
+			AnimationFrame.cancel(frame);
+		};
+	}, [enableIdleState, open]);
+
+	useIsoLayoutEffect(() => {
+		if (!open || !enableIdleState) {
+			return undefined;
+		}
+
+		if (open && mounted && transitionStatus !== 'idle') {
+			setTransitionStatus('starting');
+		}
+
+		const frame = AnimationFrame.request(() => {
+			setTransitionStatus('idle');
+		});
+
+		return () => {
+			AnimationFrame.cancel(frame);
+		};
+	}, [enableIdleState, open, mounted, transitionStatus]);
+
+	return {
+		mounted,
+		setMounted,
+		transitionStatus,
+	};
+}

package/src/internals/useValueChanged.ts

@@ -0,0 +1,18 @@
+/** @jsxImportSource octane */
+'use client';
+import * as React from 'octane';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+
+export function useValueChanged<T>(value: T, onChange: (previousValue: T) => void) {
+	const valueRef = React.useRef(value);
+	const onChangeCallback = useStableCallback(onChange);
+
+	useIsoLayoutEffect(() => {
+		if (valueRef.current !== value) {
+			onChangeCallback(valueRef.current);
+		}
+
+		valueRef.current = value;
+	}, [value, onChangeCallback]);
+}

package/src/menu/arrow/MenuArrow.tsrx

@@ -0,0 +1,71 @@
+'use client';
+import type * as React from 'octane';
+import { useMenuPositionerContext } from '../positioner/MenuPositionerContext';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { Side, Align } from '../../internals/useAnchorPositioning';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { popupStateMapping } from '../../utils/popupStateMapping';
+
+/**
+ * Displays an element positioned against the menu anchor.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
+ */
+export const MenuArrow = function MenuArrow(
+	componentPropsWithRef: React.PropsWithoutRef<MenuArrow.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+
+	const { store } = useMenuRootContext();
+	const { arrowRef, side, align, arrowUncentered, arrowStyles } = useMenuPositionerContext();
+	const open = store.useState('open');
+
+	const state: MenuArrowState = {
+		open,
+		side,
+		align,
+		uncentered: arrowUncentered,
+	};
+
+	return useRenderElement('div', componentProps, {
+		ref: [arrowRef, forwardedRef],
+		stateAttributesMapping: popupStateMapping,
+		state,
+		props: {
+			style: arrowStyles,
+			'aria-hidden': true,
+			...elementProps,
+		},
+	});
+};
+
+export interface MenuArrowState {
+	/**
+	 * Whether the menu 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 arrow cannot be centered on the anchor.
+	 */
+	uncentered: boolean;
+}
+
+export interface MenuArrowProps extends BaseUIComponentProps<'div', MenuArrowState> {}
+
+export namespace MenuArrow {
+	export type State = MenuArrowState;
+	export type Props = MenuArrowProps;
+}

package/src/menu/arrow/MenuArrowDataAttributes.ts

@@ -0,0 +1,24 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the menu popup is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the menu popup is closed.
+ */
+export const closed = CommonPopupDataAttributes.closed;
+/**
+ * Indicates which side the popup is positioned relative to the anchor.
+ * @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 when the menu arrow is uncentered.
+ */
+export const uncentered = 'data-uncentered';

package/src/menu/backdrop/MenuBackdrop.tsrx

@@ -0,0 +1,75 @@
+'use client';
+import type * as React from 'octane';
+import { useMenuRootContext } from '../root/MenuRootContext';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps } from '../../internals/types';
+import { popupTransitionStateMapping } from '../../utils/popupStateMapping';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+import { useContextMenuRootContext } from '../../context-menu/root/ContextMenuRootContext';
+import { REASONS } from '../../internals/reasons';
+
+/**
+ * An overlay displayed beneath the menu popup.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Menu](https://base-ui.com/react/components/menu)
+ */
+export const MenuBackdrop = function MenuBackdrop(
+	componentPropsWithRef: React.PropsWithoutRef<MenuBackdrop.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, ...elementProps } = componentProps;
+
+	const { store } = useMenuRootContext();
+	const open = store.useState('open');
+	const mounted = store.useState('mounted');
+	const transitionStatus = store.useState('transitionStatus');
+	const lastOpenChangeReason = store.useState('lastOpenChangeReason');
+
+	const contextMenuContext = useContextMenuRootContext();
+
+	const state: MenuBackdropState = {
+		open,
+		transitionStatus,
+	};
+
+	return useRenderElement('div', componentProps, {
+		ref: contextMenuContext?.backdropRef
+			? [forwardedRef, contextMenuContext.backdropRef]
+			: forwardedRef,
+		state,
+		stateAttributesMapping: popupTransitionStateMapping,
+		props: [
+			{
+				role: 'presentation',
+				hidden: !mounted,
+				style: {
+					pointerEvents: lastOpenChangeReason === REASONS.triggerHover ? 'none' : undefined,
+					userSelect: 'none',
+					WebkitUserSelect: 'none',
+				},
+			},
+			elementProps,
+		],
+	});
+};
+
+export interface MenuBackdropState {
+	/**
+	 * Whether the menu is currently open.
+	 */
+	open: boolean;
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+}
+
+export interface MenuBackdropProps extends BaseUIComponentProps<'div', MenuBackdropState> {}
+
+export namespace MenuBackdrop {
+	export type State = MenuBackdropState;
+	export type Props = MenuBackdropProps;
+}

package/src/menu/backdrop/MenuBackdropDataAttributes.ts

@@ -0,0 +1,18 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the menu is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the menu is closed.
+ */
+export const closed = CommonPopupDataAttributes.closed;
+/**
+ * Present when the menu begins animating in.
+ */
+export const startingStyle = CommonPopupDataAttributes.startingStyle;
+/**
+ * Present when the menu is animating out.
+ */
+export const endingStyle = CommonPopupDataAttributes.endingStyle;