@octanejs/base-ui 0.1.50 → 0.1.51

package/src/drawer/popup/DrawerPopup.tsrx

@@ -0,0 +1,485 @@
+'use client';
+import * as React from 'octane';
+import { error } from '@octanejs/base-ui-utils/error';
+import type { SafeReact } from '@octanejs/base-ui-utils/safeReact';
+import type { InteractionType } from '@octanejs/base-ui-utils/useEnhancedClickHandler';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useStableCallback } from '@octanejs/base-ui-utils/useStableCallback';
+import { EMPTY_OBJECT } from '@octanejs/base-ui-utils/empty';
+import { FloatingFocusManager } from '../../floating-ui-react';
+import { useDialogRootContext } from '../../dialog/root/DialogRootContext';
+import { useRenderElement } from '../../internals/useRenderElement.tsrx';
+import type { BaseUIComponentProps } from '../../internals/types';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+import type { StateAttributesMapping } from '../../internals/getStateAttributesProps';
+import { popupTransitionStateMapping } from '../../utils/popupStateMapping';
+import * as DrawerBackdropCssVars from '../backdrop/DrawerBackdropCssVars';
+import * as DrawerPopupCssVars from './DrawerPopupCssVars';
+import * as DrawerPopupDataAttributes from './DrawerPopupDataAttributes';
+import { useDialogPortalContext } from '../../dialog/portal/DialogPortalContext';
+import { useOpenChangeComplete } from '../../internals/useOpenChangeComplete.tsrx';
+import { COMPOSITE_KEYS } from '../../internals/composite/composite';
+import { useDrawerRootContext, type DrawerSwipeDirection } from '../root/DrawerRootContext';
+import { getSnapPointSwipeMovement, useDrawerSnapPoints } from '../root/useDrawerSnapPoints';
+import { useDrawerViewportContext } from '../viewport/DrawerViewportContext.tsrx';
+import { FOCUSABLE_POPUP_PROPS } from '../../utils/popups';
+
+// Module-level flag to ensure we only register the CSS properties once,
+// regardless of how many Drawer components are mounted.
+let drawerSwipeVarsRegistered = false;
+
+/**
+ * Removes inheritance of high-frequency drawer swipe CSS variables, which
+ * reduces style recalculation cost in complex drawers with deep subtrees.
+ * See https://motion.dev/blog/web-animation-performance-tier-list
+ * under the "Improving CSS variable performance" section.
+ */
+function removeCSSVariableInheritance() {
+	if (drawerSwipeVarsRegistered) {
+		return;
+	}
+
+	// Intentionally keep inheritance disabled on WebKit as well. Safari doesn't support
+	// opting descendants back in via `--var: inherit` for custom properties registered
+	// with `inherits: false`, but Drawer does not rely on descendant access to these vars
+	// (unlike ScrollArea), so we keep the performance optimization enabled.
+	if (typeof CSS !== 'undefined' && 'registerProperty' in CSS) {
+		[
+			DrawerPopupCssVars.swipeMovementX,
+			DrawerPopupCssVars.swipeMovementY,
+			DrawerPopupCssVars.snapPointOffset,
+		].forEach((name) => {
+			try {
+				CSS.registerProperty({
+					name,
+					syntax: '<length>',
+					inherits: false,
+					initialValue: '0px',
+				});
+			} catch {
+				/* ignore already-registered */
+			}
+		});
+
+		[
+			{
+				name: DrawerBackdropCssVars.swipeProgress,
+				initialValue: '0',
+			},
+			{
+				name: DrawerPopupCssVars.swipeStrength,
+				initialValue: '1',
+			},
+		].forEach(({ name, initialValue }) => {
+			try {
+				CSS.registerProperty({
+					name,
+					syntax: '<number>',
+					inherits: false,
+					initialValue,
+				});
+			} catch {
+				/* ignore already-registered */
+			}
+		});
+	}
+
+	drawerSwipeVarsRegistered = true;
+}
+
+const stateAttributesMapping: StateAttributesMapping<DrawerPopupState> = {
+	...popupTransitionStateMapping,
+	expanded(value) {
+		return value ? { [DrawerPopupDataAttributes.expanded]: '' } : null;
+	},
+	nestedDrawerOpen(value) {
+		return value ? { [DrawerPopupDataAttributes.nestedDrawerOpen]: '' } : null;
+	},
+	nestedDrawerSwiping(value) {
+		return value ? { [DrawerPopupDataAttributes.nestedDrawerSwiping]: '' } : null;
+	},
+	swipeDirection(value) {
+		return { [DrawerPopupDataAttributes.swipeDirection]: value };
+	},
+	swiping(value) {
+		return value ? { [DrawerPopupDataAttributes.swiping]: '' } : null;
+	},
+};
+
+/**
+ * A container for the drawer contents.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI Drawer](https://base-ui.com/react/components/drawer)
+ */
+export const DrawerPopup = function DrawerPopup(
+	componentPropsWithRef: React.PropsWithoutRef<DrawerPopup.Props> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, finalFocus, initialFocus, ...elementProps } = componentProps;
+
+	const store = useDialogRootContext();
+	const popupRef = store.context.popupRef;
+
+	const {
+		swipeDirection,
+		frontmostHeight,
+		hasNestedDrawer,
+		nestedSwiping,
+		nestedSwipeProgressStore,
+		onPopupHeightChange,
+		notifyParentFrontmostHeight,
+		notifyParentHasNestedDrawer,
+	} = useDrawerRootContext();
+
+	const descriptionElementId = store.useState('descriptionElementId');
+	const disablePointerDismissal = store.useState('disablePointerDismissal');
+	const floatingRootContext = store.useState('floatingRootContext');
+	const rootPopupProps = store.useState('popupProps');
+	const modal = store.useState('modal');
+	const mounted = store.useState('mounted');
+	const nested = store.useState('nested');
+	const nestedOpenDrawerCount = store.useState('nestedOpenDrawerCount');
+	const transitionStatus = store.useState('transitionStatus');
+	const open = store.useState('open');
+	const openMethod = store.useState('openMethod');
+	const titleElementId = store.useState('titleElementId');
+	const role = store.useState('role');
+	const floatingId = floatingRootContext.useState('floatingId');
+
+	const popupId = elementProps.id ?? floatingId;
+
+	const swipe = useDrawerViewportContext();
+	useDialogPortalContext();
+	const { snapPoints, activeSnapPoint, activeSnapPointOffset } = useDrawerSnapPoints();
+
+	const nestedDrawerOpen = nestedOpenDrawerCount > 0;
+	const swiping = swipe?.swiping ?? false;
+	const swipeStrength = swipe?.swipeStrength ?? null;
+
+	const [popupHeight, setPopupHeight] = React.useState(0);
+	const popupHeightRef = React.useRef(0);
+
+	/* istanbul ignore else -- process.env.NODE_ENV is a build-time constant. */
+	if (process.env.NODE_ENV !== 'production') {
+		// eslint-disable-next-line react-hooks/rules-of-hooks
+		React.useEffect(() => {
+			if (swipe) {
+				return;
+			}
+
+			const ownerStackMessage = '';
+			const message =
+				'<Drawer.Popup> expected to be rendered within <Drawer.Viewport>. Omitting the ' +
+				'viewport disables drawer swipe handling and touch scroll locking. Wrap ' +
+				'<Drawer.Popup> in <Drawer.Viewport>.';
+			error(`${message}${ownerStackMessage}`);
+		}, [swipe]);
+	}
+
+	const measureHeight = useStableCallback(() => {
+		const popupElement = popupRef.current;
+		if (!popupElement) {
+			return;
+		}
+
+		const offsetHeight = popupElement.offsetHeight;
+
+		// Only skip while the element is still actually stretched beyond its last measured height.
+		if (
+			popupHeightRef.current > 0 &&
+			frontmostHeight > popupHeightRef.current &&
+			offsetHeight > popupHeightRef.current
+		) {
+			return;
+		}
+
+		const keepHeightWhileNested = popupHeightRef.current > 0 && hasNestedDrawer;
+		if (keepHeightWhileNested) {
+			const oldHeight = popupHeightRef.current;
+			setPopupHeight(oldHeight);
+			onPopupHeightChange(oldHeight);
+			return;
+		}
+
+		const nextHeight = offsetHeight;
+		if (nextHeight === popupHeightRef.current) {
+			return;
+		}
+
+		popupHeightRef.current = nextHeight;
+		setPopupHeight(nextHeight);
+		onPopupHeightChange(nextHeight);
+	});
+
+	useIsoLayoutEffect(() => {
+		if (!mounted) {
+			popupHeightRef.current = 0;
+			setPopupHeight(0);
+			onPopupHeightChange(0);
+			return undefined;
+		}
+
+		const popupElement = popupRef.current;
+		if (!popupElement) {
+			return undefined;
+		}
+
+		removeCSSVariableInheritance();
+		measureHeight();
+
+		if (typeof ResizeObserver !== 'function') {
+			return undefined;
+		}
+
+		const resizeObserver = new ResizeObserver(measureHeight);
+
+		resizeObserver.observe(popupElement);
+		return () => {
+			resizeObserver.disconnect();
+		};
+	}, [measureHeight, mounted, nestedDrawerOpen, onPopupHeightChange, popupRef]);
+
+	useIsoLayoutEffect(() => {
+		const syncNestedSwipeProgress = () => {
+			const popupElement = popupRef.current;
+			if (!popupElement) {
+				return;
+			}
+
+			const progress = nestedSwipeProgressStore.getSnapshot();
+			if (progress > 0) {
+				popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, `${progress}`);
+			} else {
+				popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, '0');
+			}
+		};
+
+		syncNestedSwipeProgress();
+		const unsubscribe = nestedSwipeProgressStore.subscribe(syncNestedSwipeProgress);
+		const popupElement = popupRef.current;
+
+		return () => {
+			unsubscribe();
+			if (popupElement) {
+				popupElement.style.setProperty(DrawerBackdropCssVars.swipeProgress, '0');
+			}
+		};
+	}, [nestedSwipeProgressStore, popupRef]);
+
+	useIsoLayoutEffect(() => {
+		if (!open) {
+			return undefined;
+		}
+
+		notifyParentFrontmostHeight?.(frontmostHeight);
+
+		return () => {
+			notifyParentFrontmostHeight?.(0);
+		};
+	}, [frontmostHeight, open, notifyParentFrontmostHeight]);
+
+	useIsoLayoutEffect(() => {
+		if (!notifyParentHasNestedDrawer) {
+			return undefined;
+		}
+
+		const present = open || transitionStatus === 'ending';
+		notifyParentHasNestedDrawer(present);
+
+		return () => {
+			notifyParentHasNestedDrawer(false);
+		};
+	}, [notifyParentHasNestedDrawer, open, transitionStatus]);
+
+	useOpenChangeComplete({
+		open,
+		ref: popupRef,
+		onComplete() {
+			if (open) {
+				store.context.onOpenChangeComplete?.(true);
+			}
+		},
+	});
+
+	const resolvedInitialFocus = initialFocus === undefined ? popupRef : initialFocus;
+
+	const setPopupElement = store.useStateSetter('popupElement');
+
+	const state: DrawerPopupState = {
+		open,
+		nested,
+		transitionStatus,
+		expanded: activeSnapPoint === 1,
+		nestedDrawerOpen,
+		nestedDrawerSwiping: nestedSwiping,
+		swipeDirection,
+		swiping,
+	};
+
+	let popupHeightCssVarValue: string | undefined;
+	const shouldUseAutoHeight = !hasNestedDrawer && transitionStatus !== 'ending';
+	if (popupHeight && !shouldUseAutoHeight) {
+		popupHeightCssVarValue = `${popupHeight}px`;
+	}
+
+	const shouldApplySnapPoints =
+		snapPoints && snapPoints.length > 0 && (swipeDirection === 'down' || swipeDirection === 'up');
+	let snapPointOffsetValue: number | null = null;
+	if (shouldApplySnapPoints && activeSnapPointOffset !== null) {
+		snapPointOffsetValue = swipeDirection === 'up' ? -activeSnapPointOffset : activeSnapPointOffset;
+	}
+
+	let dragStyles = swipe ? swipe.getDragStyles() : EMPTY_OBJECT;
+	if (shouldApplySnapPoints && swipeDirection === 'down') {
+		const baseOffset = activeSnapPointOffset ?? 0;
+		const movementValue = Number.parseFloat(
+			String((dragStyles as Record<string, string>)[DrawerPopupCssVars.swipeMovementY]),
+		);
+
+		if (swiping && Number.isFinite(movementValue)) {
+			dragStyles = {
+				...dragStyles,
+				transform: undefined,
+				[DrawerPopupCssVars.swipeMovementY]: `${getSnapPointSwipeMovement(
+					baseOffset,
+					movementValue,
+				)}px`,
+			} as React.CSSProperties;
+		} else {
+			dragStyles = {
+				...dragStyles,
+				transform: undefined,
+			};
+		}
+	}
+
+	const element = useRenderElement('div', componentProps, {
+		state,
+		props: [
+			rootPopupProps,
+			{
+				id: popupId,
+				'aria-labelledby': titleElementId,
+				'aria-describedby': descriptionElementId,
+				role,
+				...FOCUSABLE_POPUP_PROPS,
+				hidden: !mounted,
+				onKeyDown(event: React.KeyboardEvent) {
+					if (COMPOSITE_KEYS.has(event.key)) {
+						event.stopPropagation();
+					}
+				},
+				style: {
+					...dragStyles,
+					[DrawerBackdropCssVars.swipeProgress]: '0',
+					[DrawerPopupCssVars.nestedDrawers]: nestedOpenDrawerCount,
+					[DrawerPopupCssVars.height]: popupHeightCssVarValue,
+					[DrawerPopupCssVars.snapPointOffset]:
+						typeof snapPointOffsetValue === 'number' ? `${snapPointOffsetValue}px` : '0px',
+					[DrawerPopupCssVars.frontmostHeight]: frontmostHeight
+						? `${frontmostHeight}px`
+						: undefined,
+					[DrawerPopupCssVars.swipeStrength]:
+						typeof swipeStrength === 'number' && Number.isFinite(swipeStrength) && swipeStrength > 0
+							? `${swipeStrength}`
+							: '1',
+				} as React.CSSProperties,
+			},
+			elementProps,
+		],
+		ref: [forwardedRef, popupRef, setPopupElement],
+		stateAttributesMapping,
+	});
+
+	return (
+		<FloatingFocusManager
+			context={floatingRootContext}
+			openInteractionType={openMethod}
+			disabled={!mounted}
+			closeOnFocusOut={!disablePointerDismissal}
+			initialFocus={resolvedInitialFocus}
+			returnFocus={finalFocus}
+			modal={modal !== false}
+			restoreFocus="popup"
+		>
+			{element}
+		</FloatingFocusManager>
+	);
+};
+
+export interface DrawerPopupProps extends BaseUIComponentProps<'div', DrawerPopupState> {
+	/**
+	 * Determines the element to focus when the drawer is opened.
+	 *
+	 * - `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, or `false`/`undefined` to do nothing.
+	 */
+	initialFocus?:
+		| boolean
+		| React.RefObject<HTMLElement | null>
+		| ((openType: InteractionType) => boolean | HTMLElement | null | void)
+		| undefined;
+	/**
+	 * Determines the element to focus when the drawer 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, or `false`/`undefined` to do nothing.
+	 */
+	finalFocus?:
+		| boolean
+		| React.RefObject<HTMLElement | null>
+		| ((closeType: InteractionType) => boolean | HTMLElement | null | void)
+		| undefined;
+}
+
+export interface DrawerPopupState {
+	/**
+	 * Whether the drawer is currently open.
+	 */
+	open: boolean;
+	/**
+	 * The transition status of the component.
+	 */
+	transitionStatus: TransitionStatus;
+	/**
+	 * Whether the active snap point is the full-height expanded state.
+	 */
+	expanded: boolean;
+	/**
+	 * Whether the drawer is nested within a parent drawer.
+	 */
+	nested: boolean;
+	/**
+	 * Whether the drawer has nested drawers open.
+	 */
+	nestedDrawerOpen: boolean;
+	/**
+	 * Whether a nested drawer is currently being swiped.
+	 */
+	nestedDrawerSwiping: boolean;
+	/**
+	 * The swipe direction used to dismiss the drawer.
+	 */
+	swipeDirection: DrawerSwipeDirection;
+	/**
+	 * Whether the drawer is being swiped.
+	 */
+	swiping: boolean;
+}
+
+export namespace DrawerPopup {
+	export type Props = DrawerPopupProps;
+	export type State = DrawerPopupState;
+}
+
+// Bundlers replace this expression; keep the build constant local to this module.
+declare const process: { env: { NODE_ENV?: string } };

package/src/drawer/popup/DrawerPopupCssVars.ts

@@ -0,0 +1,35 @@
+/**
+ * The number of nested drawers that are currently open.
+ * @type {number}
+ */
+export const nestedDrawers = '--nested-drawers';
+/**
+ * The height of the drawer popup.
+ * @type {CSS length}
+ */
+export const height = '--drawer-height';
+/**
+ * The height of the frontmost open drawer in the current nested drawer stack.
+ * @type {CSS length}
+ */
+export const frontmostHeight = '--drawer-frontmost-height';
+/**
+ * The swipe movement on the X axis.
+ * @type {CSS length}
+ */
+export const swipeMovementX = '--drawer-swipe-movement-x';
+/**
+ * The swipe movement on the Y axis.
+ * @type {CSS length}
+ */
+export const swipeMovementY = '--drawer-swipe-movement-y';
+/**
+ * The snap point offset used for translating the drawer.
+ * @type {CSS length}
+ */
+export const snapPointOffset = '--drawer-snap-point-offset';
+/**
+ * A scalar (0.1-1) used to scale the swipe release transition duration in CSS.
+ * @type {number}
+ */
+export const swipeStrength = '--drawer-swipe-strength';

package/src/drawer/popup/DrawerPopupDataAttributes.ts

@@ -0,0 +1,43 @@
+import { CommonPopupDataAttributes } from '../../utils/popupStateMapping';
+
+/**
+ * Present when the drawer is open.
+ */
+export const open = CommonPopupDataAttributes.open;
+/**
+ * Present when the drawer is closed.
+ */
+export const closed = CommonPopupDataAttributes.closed;
+/**
+ * Present when the drawer begins animating in.
+ */
+export const startingStyle = CommonPopupDataAttributes.startingStyle;
+/**
+ * Present when the drawer is animating out.
+ */
+export const endingStyle = CommonPopupDataAttributes.endingStyle;
+/**
+ * Present when the drawer is at the expanded (full-height) snap point.
+ */
+export const expanded = 'data-expanded';
+/**
+ * Present when a nested drawer is open.
+ */
+export const nestedDrawerOpen = 'data-nested-drawer-open';
+/**
+ * Present when a nested drawer is being swiped.
+ */
+export const nestedDrawerSwiping = 'data-nested-drawer-swiping';
+/**
+ * Present when the drawer is dismissed by swiping.
+ */
+export const swipeDismiss = 'data-swipe-dismiss';
+/**
+ * Indicates the swipe direction.
+ * @type {'up' | 'down' | 'left' | 'right'}
+ */
+export const swipeDirection = 'data-swipe-direction';
+/**
+ * Present when the drawer is being swiped.
+ */
+export const swiping = 'data-swiping';

package/src/drawer/portal/DrawerPortal.tsrx

@@ -0,0 +1,39 @@
+'use client';
+import type * as React from 'octane';
+import { DialogPortal } from '../../dialog/portal/DialogPortal.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 Drawer](https://base-ui.com/react/components/drawer)
+ */
+export const DrawerPortal = DialogPortal as DrawerPortal;
+
+export interface DrawerPortalState {}
+
+export interface DrawerPortalProps extends BaseUIComponentProps<'div', DrawerPortalState> {
+	/**
+	 * 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 interface DrawerPortal {
+	(
+		componentProps: DrawerPortalProps & React.RefAttributes<HTMLDivElement>,
+	): React.ReactElement | null;
+}
+
+export namespace DrawerPortal {
+	export type Props = DrawerPortalProps;
+	export type State = DrawerPortalState;
+}