@octanejs/base-ui 0.1.50 → 0.1.52

package/src/floating-ui-react/components/FloatingPortal.tsrx

@@ -0,0 +1,319 @@
+import type { HTMLProps } from '../../types';
+import type { WithBaseUIEvent } from '../../internals/types';
+('use client');
+import * as React from 'octane';
+import * as ReactDOM from 'octane';
+import { isNode } from '@floating-ui/utils/dom';
+import { addEventListener } from '@octanejs/base-ui-utils/addEventListener';
+import { mergeCleanups } from '@octanejs/base-ui-utils/mergeCleanups';
+import { useId } from '@octanejs/base-ui-utils/useId';
+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 { FocusGuard } from '../../utils/FocusGuard.tsrx';
+import {
+	enableFocusInside,
+	disableFocusInside,
+	getPreviousTabbable,
+	getNextTabbable,
+	isOutsideEvent,
+} from '../utils/tabbable';
+import { createChangeEventDetails } from '../../internals/createBaseUIEventDetails';
+import { REASONS } from '../../internals/reasons';
+import { createAttribute } from '../utils/createAttribute';
+import {
+	useRenderElement,
+	type UseRenderElementComponentProps,
+} from '../../internals/useRenderElement.tsrx';
+import { ownerVisuallyHidden } from '../../internals/constants';
+import type { BaseUIComponentProps } from '../../internals/types';
+
+type FocusManagerState = null | {
+	modal: boolean;
+	open: boolean;
+	onOpenChange(
+		open: boolean,
+		data?: { reason?: string | undefined; event?: Event | undefined },
+	): void;
+	domReference: Element | null;
+	closeOnFocusOut: boolean;
+};
+
+const PortalContext = React.createContext<null | {
+	portalNode: HTMLElement | null;
+	setFocusManagerState: React.Dispatch<React.SetStateAction<FocusManagerState>>;
+	beforeInsideRef: React.RefObject<HTMLSpanElement | null>;
+	afterInsideRef: React.RefObject<HTMLSpanElement | null>;
+	beforeOutsideRef: React.RefObject<HTMLSpanElement | null>;
+	afterOutsideRef: React.RefObject<HTMLSpanElement | null>;
+}>(null);
+
+export const usePortalContext = () => React.useContext(PortalContext);
+
+const attr = createAttribute('portal');
+
+export interface UseFloatingPortalNodeProps {
+	ref?: React.Ref<HTMLDivElement> | undefined;
+	container?:
+		HTMLElement | ShadowRoot | null | React.RefObject<HTMLElement | ShadowRoot | null> | undefined;
+	componentProps?: UseRenderElementComponentProps<any> | undefined;
+	elementProps?: WithBaseUIEvent<HTMLProps<HTMLDivElement>> | undefined;
+}
+
+export interface UseFloatingPortalNodeResult {
+	node: HTMLElement | null;
+	/**
+	 * The `id` attribute of the portal node. On React 17 it is `undefined` until the `useId`
+	 * polyfill assigns it in an effect after the node has been created.
+	 */
+	nodeId: string | undefined;
+	subtree: React.ReactPortal | null;
+}
+
+export function useFloatingPortalNode(
+	props: UseFloatingPortalNodeProps = {},
+): UseFloatingPortalNodeResult {
+	const { ref, container: containerProp, componentProps = EMPTY_OBJECT, elementProps } = props;
+
+	const uniqueId = useId();
+	const portalContext = usePortalContext();
+	const parentPortalNode = portalContext?.portalNode;
+
+	const [containerElement, setContainerElement] = React.useState<HTMLElement | ShadowRoot | null>(
+		null,
+	);
+	const [portalNode, setPortalNode] = React.useState<HTMLElement | null>(null);
+	const setPortalNodeRef = useStableCallback((node: HTMLElement | null) => {
+		if (node !== null) {
+			// the useIsoLayoutEffect below watching containerProp / parentPortalNode
+			// sets setPortalNode(null) when the container becomes null or changes.
+			// So even though the ref callback now ignores null, the portal node still gets cleared.
+			setPortalNode(node);
+		}
+	});
+
+	const containerRef = React.useRef<HTMLElement | ShadowRoot | null>(null);
+
+	useIsoLayoutEffect(() => {
+		// Wait for the container to be resolved if explicitly `null`.
+		if (containerProp === null) {
+			if (containerRef.current) {
+				containerRef.current = null;
+				setPortalNode(null);
+				setContainerElement(null);
+			}
+			return;
+		}
+
+		const resolvedContainer =
+			(containerProp && (isNode(containerProp) ? containerProp : containerProp.current)) ??
+			parentPortalNode ??
+			document.body;
+
+		if (resolvedContainer == null) {
+			if (containerRef.current) {
+				containerRef.current = null;
+				setPortalNode(null);
+				setContainerElement(null);
+			}
+			return;
+		}
+
+		if (containerRef.current !== resolvedContainer) {
+			containerRef.current = resolvedContainer;
+			setPortalNode(null);
+			setContainerElement(resolvedContainer);
+		}
+	}, [containerProp, parentPortalNode]);
+
+	const portalElement = useRenderElement('div', componentProps, {
+		ref: [ref, setPortalNodeRef],
+		props: [
+			{
+				id: uniqueId,
+				[attr]: '',
+			},
+			elementProps,
+		],
+	});
+
+	// This `createPortal` call injects `portalElement` into the `container`.
+	// Another call inside `FloatingPortal`/`FloatingPortalLite` then injects the children into `portalElement`.
+	const portalSubtree =
+		containerElement && portalElement
+			? ReactDOM.createPortal(portalElement, containerElement)
+			: null;
+
+	return {
+		node: portalNode,
+		// `id` and `render` props can override or remove the generated ID. Use the exact
+		// rendered value so `aria-owns` never points at an ID absent from the DOM.
+		nodeId: React.isValidElement<{ id?: string | undefined }>(portalElement)
+			? portalElement.props.id
+			: undefined,
+		subtree: portalSubtree,
+	};
+}
+
+/**
+ * Portals the floating element into a given container element — by default,
+ * outside of the app root and into the body.
+ * This is necessary to ensure the floating element can appear outside any
+ * potential parent containers that cause clipping (such as `overflow: hidden`),
+ * while retaining its location in the React tree.
+ * @see https://floating-ui.com/docs/FloatingPortal
+ * @internal
+ */
+export const FloatingPortal = function FloatingPortal(
+	componentPropsWithRef: React.PropsWithoutRef<FloatingPortal.Props<any>> & {
+		ref?: React.Ref<HTMLDivElement>;
+	},
+) {
+	const { ref: forwardedRef = null, ...componentProps } = componentPropsWithRef;
+	const { render, className, style, children, container, portalOwnerRole, ...elementProps } =
+		componentProps;
+
+	const {
+		node: portalNode,
+		nodeId: portalNodeId,
+		subtree: portalSubtree,
+	} = useFloatingPortalNode({
+		container,
+		ref: forwardedRef,
+		componentProps,
+		elementProps,
+	});
+
+	const beforeOutsideRef = React.useRef<HTMLSpanElement | null>(null);
+	const afterOutsideRef = React.useRef<HTMLSpanElement | null>(null);
+	const beforeInsideRef = React.useRef<HTMLSpanElement | null>(null);
+	const afterInsideRef = React.useRef<HTMLSpanElement | null>(null);
+
+	const [focusManagerState, setFocusManagerState] = React.useState<FocusManagerState>(null);
+	const focusInsideDisabledRef = React.useRef(false);
+
+	const modal = focusManagerState?.modal;
+	const open = focusManagerState?.open;
+
+	const shouldRenderGuards =
+		!!focusManagerState && !focusManagerState.modal && focusManagerState.open && !!portalNode;
+
+	// https://codesandbox.io/s/tabbable-portal-f4tng?file=/src/TabbablePortal.tsx
+	React.useEffect(() => {
+		if (!portalNode || modal) {
+			return undefined;
+		}
+
+		// Make sure elements inside the portal element are tabbable only when the
+		// portal has already been focused, either by tabbing into a focus trap
+		// element outside or using the mouse.
+		function onFocus(event: FocusEvent) {
+			if (portalNode && event.relatedTarget && isOutsideEvent(event)) {
+				if (event.type === 'focusin') {
+					if (focusInsideDisabledRef.current) {
+						enableFocusInside(portalNode);
+						focusInsideDisabledRef.current = false;
+					}
+				} else {
+					disableFocusInside(portalNode);
+					focusInsideDisabledRef.current = true;
+				}
+			}
+		}
+
+		// Listen to the event on the capture phase so they run before the focus
+		// trap elements onFocus prop is called.
+		return mergeCleanups(
+			addEventListener(portalNode, 'focusin', onFocus, true),
+			addEventListener(portalNode, 'focusout', onFocus, true),
+		);
+	}, [portalNode, modal]);
+
+	useIsoLayoutEffect(() => {
+		if (!portalNode || open !== true || !focusInsideDisabledRef.current) {
+			return;
+		}
+
+		// Restore tabbability before the focus manager's queued focus-on-open step runs.
+		enableFocusInside(portalNode);
+		focusInsideDisabledRef.current = false;
+	}, [open, portalNode]);
+
+	const portalContextValue = React.useMemo(
+		() => ({
+			beforeOutsideRef,
+			afterOutsideRef,
+			beforeInsideRef,
+			afterInsideRef,
+			portalNode,
+			setFocusManagerState,
+		}),
+		[portalNode],
+	);
+
+	return (
+		<React.Fragment>
+			{portalSubtree}
+			<PortalContext.Provider value={portalContextValue}>
+				{shouldRenderGuards && portalNode && (
+					<FocusGuard
+						data-type="outside"
+						ref={beforeOutsideRef}
+						onFocus={(event) => {
+							if (isOutsideEvent(event, portalNode)) {
+								beforeInsideRef.current?.focus();
+							} else {
+								const domReference = focusManagerState ? focusManagerState.domReference : null;
+								const prevTabbable = getPreviousTabbable(domReference);
+								prevTabbable?.focus();
+							}
+						}}
+					/>
+				)}
+				{shouldRenderGuards && portalNode && (
+					<span role={portalOwnerRole} aria-owns={portalNodeId} style={ownerVisuallyHidden} />
+				)}
+				{portalNode && ReactDOM.createPortal(children, portalNode)}
+				{shouldRenderGuards && portalNode && (
+					<FocusGuard
+						data-type="outside"
+						ref={afterOutsideRef}
+						onFocus={(event) => {
+							if (isOutsideEvent(event, portalNode)) {
+								afterInsideRef.current?.focus();
+							} else {
+								const domReference = focusManagerState ? focusManagerState.domReference : null;
+								const nextTabbable = getNextTabbable(domReference);
+								nextTabbable?.focus();
+
+								if (focusManagerState?.closeOnFocusOut) {
+									focusManagerState?.onOpenChange(
+										false,
+										createChangeEventDetails(REASONS.focusOut, event),
+									);
+								}
+							}
+						}}
+					/>
+				)}
+			</PortalContext.Provider>
+		</React.Fragment>
+	);
+};
+
+export interface FloatingPortalState {}
+
+export namespace FloatingPortal {
+	export type State = FloatingPortalState;
+	export interface Props<TState> extends BaseUIComponentProps<'div', TState> {
+		/**
+		 * A parent element to render the portal element into.
+		 */
+		container?: UseFloatingPortalNodeProps['container'] | undefined;
+		/**
+		 * @ignore
+		 * The role for the hidden `aria-owns` owner element.
+		 */
+		portalOwnerRole?: React.AriaRole | undefined;
+	}
+}

package/src/floating-ui-react/components/FloatingRootStore.ts

@@ -0,0 +1,136 @@
+import type * as React from 'octane';
+import { ReactStore } from '@octanejs/base-ui-utils/store';
+import type { FloatingEvents, ContextData, ReferenceType } from '../types';
+import { type BaseUIChangeEventDetails } from '../../internals/createBaseUIEventDetails';
+import { createEventEmitter } from '../utils/createEventEmitter';
+import { type FloatingUIOpenChangeDetails } from '../../internals/types';
+import { type PopupTriggerMap } from '../../utils/popups';
+import { isClickLikeEvent } from '../utils';
+import type { TransitionStatus } from '../../internals/useTransitionStatus';
+
+export interface FloatingRootState {
+	open: boolean;
+	transitionStatus: TransitionStatus | undefined;
+	domReferenceElement: Element | null;
+	referenceElement: ReferenceType | null;
+	floatingElement: HTMLElement | null;
+	positionReference: ReferenceType | null;
+	/**
+	 * The ID of the floating element.
+	 */
+	floatingId: string | undefined;
+}
+
+export interface FloatingRootStoreContext {
+	onOpenChange:
+		((open: boolean, eventDetails: BaseUIChangeEventDetails<string>) => void) | undefined;
+	readonly dataRef: React.RefObject<ContextData>;
+	readonly events: FloatingEvents;
+	nested: boolean;
+	readonly triggerElements: PopupTriggerMap;
+}
+
+const selectors = {
+	open: (state: FloatingRootState) => state.open,
+	transitionStatus: (state: FloatingRootState) => state.transitionStatus,
+	domReferenceElement: (state: FloatingRootState) => state.domReferenceElement,
+	referenceElement: (state: FloatingRootState) => state.positionReference ?? state.referenceElement,
+	floatingElement: (state: FloatingRootState) => state.floatingElement,
+	floatingId: (state: FloatingRootState) => state.floatingId,
+};
+
+interface FloatingRootStoreOptions {
+	open: boolean;
+	transitionStatus: TransitionStatus | undefined;
+	referenceElement: ReferenceType | null;
+	floatingElement: HTMLElement | null;
+	triggerElements: PopupTriggerMap;
+	floatingId: string | undefined;
+	/**
+	 * When true, `setOpen` only forwards to `onOpenChange`.
+	 * The popup store owns `dispatchOpenChange(...)` in this mode.
+	 */
+	syncOnly: boolean;
+	nested: boolean;
+	onOpenChange:
+		((open: boolean, eventDetails: BaseUIChangeEventDetails<string>) => void) | undefined;
+}
+
+export class FloatingRootStore extends ReactStore<
+	Readonly<FloatingRootState>,
+	FloatingRootStoreContext,
+	typeof selectors
+> {
+	private readonly syncOnly: boolean;
+
+	constructor(options: FloatingRootStoreOptions) {
+		const { syncOnly, nested, onOpenChange, triggerElements, ...initialState } = options;
+
+		super(
+			{
+				...initialState,
+				positionReference: initialState.referenceElement,
+				domReferenceElement: initialState.referenceElement as Element | null,
+			},
+			{
+				onOpenChange,
+				dataRef: { current: {} },
+				events: createEventEmitter(),
+				nested,
+				triggerElements,
+			},
+			selectors,
+		);
+
+		this.syncOnly = syncOnly;
+	}
+
+	/**
+	 * Syncs the event used by hover logic to distinguish hover-open from click-like interaction.
+	 */
+	syncOpenEvent = (newOpen: boolean, event: Event | undefined) => {
+		if (
+			!newOpen ||
+			!this.state.open ||
+			// Prevent a pending hover-open from overwriting a click-open event, while allowing
+			// click events to upgrade a hover-open.
+			(event != null && isClickLikeEvent(event))
+		) {
+			this.context.dataRef.current.openEvent = newOpen ? event : undefined;
+		}
+	};
+
+	/**
+	 * Runs the root-owned side effects for an open state change.
+	 */
+	dispatchOpenChange = (newOpen: boolean, eventDetails: BaseUIChangeEventDetails<string>) => {
+		this.syncOpenEvent(newOpen, eventDetails.event);
+
+		const details: FloatingUIOpenChangeDetails = {
+			open: newOpen,
+			reason: eventDetails.reason,
+			nativeEvent: eventDetails.event,
+			nested: this.context.nested,
+			triggerElement: eventDetails.trigger,
+		};
+
+		this.context.events.emit('openchange', details);
+	};
+
+	/**
+	 * Emits the `openchange` event through the internal event emitter and calls the `onOpenChange` handler with the provided arguments.
+	 *
+	 * @param newOpen The new open state.
+	 * @param eventDetails Details about the event that triggered the open state change.
+	 */
+	setOpen = (newOpen: boolean, eventDetails: BaseUIChangeEventDetails<string>) => {
+		if (this.syncOnly) {
+			this.context.onOpenChange?.(newOpen, eventDetails);
+			return;
+		}
+
+		this.dispatchOpenChange(newOpen, eventDetails);
+
+		this.context.onOpenChange?.(newOpen, eventDetails);
+	};
+}

package/src/floating-ui-react/components/FloatingTree.tsrx

@@ -0,0 +1,95 @@
+'use client';
+import * as React from 'octane';
+
+import { useId } from '@octanejs/base-ui-utils/useId';
+import { useIsoLayoutEffect } from '@octanejs/base-ui-utils/useIsoLayoutEffect';
+import { useRefWithInit } from '@octanejs/base-ui-utils/useRefWithInit';
+import type { FloatingNodeType, FloatingTreeType } from '../types';
+import { FloatingTreeStore } from './FloatingTreeStore';
+
+const FloatingNodeContext = React.createContext<FloatingNodeType | null>(null);
+const FloatingTreeContext = React.createContext<FloatingTreeType | null>(null);
+
+/**
+ * Returns the parent node id for nested floating elements, if available.
+ * Returns `null` for top-level floating elements.
+ */
+export const useFloatingParentNodeId = (): string | null =>
+	React.useContext(FloatingNodeContext)?.id || null;
+
+/**
+ * Returns the nearest floating tree context, if available.
+ */
+export const useFloatingTree = (externalTree?: FloatingTreeStore): FloatingTreeType | null => {
+	const contextTree = React.useContext(FloatingTreeContext) as FloatingTreeType | null;
+	return externalTree ?? contextTree;
+};
+
+/**
+ * Registers a node into the `FloatingTree`, returning its id.
+ * @see https://floating-ui.com/docs/FloatingTree
+ */
+export function useFloatingNodeId(externalTree?: FloatingTreeStore): string | undefined {
+	const id = useId();
+	const tree = useFloatingTree(externalTree);
+	const parentId = useFloatingParentNodeId();
+
+	useIsoLayoutEffect(() => {
+		if (!id) {
+			return undefined;
+		}
+
+		const node = { id, parentId };
+		tree?.addNode(node);
+		return () => {
+			tree?.removeNode(node);
+		};
+	}, [tree, id, parentId]);
+
+	return id;
+}
+
+export interface FloatingNodeProps {
+	children?: React.OctaneNode;
+	id: string | undefined;
+}
+
+/**
+ * Provides parent node context for nested floating elements.
+ * @see https://floating-ui.com/docs/FloatingTree
+ * @internal
+ */
+export function FloatingNode(props: FloatingNodeProps): React.ReactElement {
+	const { children, id } = props;
+
+	const parentId = useFloatingParentNodeId();
+
+	return (
+		<FloatingNodeContext.Provider value={React.useMemo(() => ({ id, parentId }), [id, parentId])}>
+			{children}
+		</FloatingNodeContext.Provider>
+	);
+}
+
+export interface FloatingTreeProps {
+	children?: React.OctaneNode;
+	externalTree?: FloatingTreeStore | undefined;
+}
+
+/**
+ * Provides context for nested floating elements when they are not children of
+ * each other on the DOM.
+ * This is not necessary in all cases, except when there must be explicit communication between parent and child floating elements. It is necessary for:
+ * - The `bubbles` option in the `useDismiss()` Hook
+ * - Nested virtual list navigation
+ * - Nested floating elements that each open on hover
+ * - Custom communication between parent and child floating elements
+ * @see https://floating-ui.com/docs/FloatingTree
+ * @internal
+ */
+export function FloatingTree(props: FloatingTreeProps): React.ReactElement {
+	const { children, externalTree } = props;
+
+	const tree = useRefWithInit(() => externalTree ?? new FloatingTreeStore()).current;
+	return <FloatingTreeContext.Provider value={tree}>{children}</FloatingTreeContext.Provider>;
+}

package/src/floating-ui-react/components/FloatingTreeStore.ts

@@ -0,0 +1,24 @@
+import type * as React from 'octane';
+import type { FloatingNodeType, FloatingEvents } from '../types';
+import { createEventEmitter } from '../utils/createEventEmitter';
+
+/**
+ * Stores and manages floating elements in a tree structure.
+ * This is a backing store for the `FloatingTree` component.
+ */
+export class FloatingTreeStore {
+	public readonly nodesRef: React.RefObject<Array<FloatingNodeType>> = { current: [] };
+
+	public readonly events: FloatingEvents = createEventEmitter();
+
+	public addNode(node: FloatingNodeType) {
+		this.nodesRef.current.push(node);
+	}
+
+	public removeNode(node: FloatingNodeType) {
+		const index = this.nodesRef.current.findIndex((n) => n === node);
+		if (index !== -1) {
+			this.nodesRef.current.splice(index, 1);
+		}
+	}
+}

package/src/floating-ui-react/hooks/gridNavigation.ts

@@ -0,0 +1,50 @@
+import type * as React from 'octane';
+import {
+	getGridNavigatedIndex,
+	isIndexOutOfListBounds,
+	type DisabledIndices,
+} from '../utils/composite';
+
+/**
+ * Positional arguments are deliberate: property names of an options object
+ * don't minify, and the signature is locked to the caller via `typeof` on the
+ * `grid` option of `useListNavigation`.
+ *
+ * The injected grid navigator only ever operates on a uniform 1x1 grid (sizes are
+ * always `1x1` and packing is never dense), so the cell-map machinery that supports
+ * multi-cell items collapses to an identity transform over the item list. Calling
+ * `getGridNavigatedIndex` directly keeps the cell-map helpers
+ * (`createGridCellMap`/`getGridCellIndexOfCorner`/`getGridCellIndices`) out of
+ * grid-combobox bundles.
+ */
+export function gridNavigation(
+	event: React.KeyboardEvent,
+	prevIndex: number,
+	listRef: React.RefObject<Array<HTMLElement | null>>,
+	orientation: 'horizontal' | 'vertical' | 'both',
+	loopFocus: boolean,
+	rtl: boolean,
+	disabledIndices: DisabledIndices | undefined,
+	minIndex: number,
+	maxIndex: number,
+	cols = 2,
+): number | undefined {
+	const nextIndex = getGridNavigatedIndex(listRef.current, {
+		event,
+		orientation,
+		loopFocus,
+		rtl,
+		cols,
+		disabledIndices,
+		minIndex,
+		maxIndex,
+		// An out-of-range previous index falls back to the first enabled item.
+		prevIndex: prevIndex > maxIndex ? minIndex : prevIndex,
+		stopEvent: true,
+	});
+
+	// `getGridNavigatedIndex` can return an out-of-bounds sentinel (e.g. `-1` when there is no
+	// previous item to move from); surface that as `undefined` so the caller treats it as
+	// "no navigation" rather than highlighting index `-1`.
+	return isIndexOutOfListBounds(listRef.current, nextIndex) ? undefined : nextIndex;
+}