@octanejs/floating-ui 0.1.9 → 0.1.10

package/src/index.ts

@@ -23,6 +23,86 @@ export {
 	size,
 } from '@floating-ui/dom';
 
+// Positioning types, re-exported from @floating-ui/dom (mirrors upstream
+// @floating-ui/react's type re-export surface).
+export type {
+	AlignedPlacement,
+	Alignment,
+	AutoPlacementOptions,
+	AutoUpdateOptions,
+	Axis,
+	Boundary,
+	ClientRectObject,
+	ComputePositionConfig,
+	ComputePositionReturn,
+	Coords,
+	Derivable,
+	DetectOverflowOptions,
+	Dimensions,
+	ElementContext,
+	ElementRects,
+	Elements,
+	FlipOptions,
+	FloatingElement,
+	HideOptions,
+	InlineOptions,
+	Length,
+	Middleware,
+	MiddlewareArguments,
+	MiddlewareData,
+	MiddlewareReturn,
+	MiddlewareState,
+	NodeScroll,
+	OffsetOptions,
+	Padding,
+	Placement,
+	Platform,
+	Rect,
+	ReferenceElement,
+	RootBoundary,
+	ShiftOptions,
+	Side,
+	SideObject,
+	SizeOptions,
+	Strategy,
+	VirtualElement,
+} from '@floating-ui/dom';
+
+// The shared octane-adapted type surface (mirrors @floating-ui/react's exported
+// type names; see ./types for the octane adaptations).
+export type {
+	ArrowOptions,
+	ContextData,
+	Delay,
+	ElementProps,
+	ExtendedElements,
+	ExtendedRefs,
+	ExtendedUserProps,
+	FloatingContext,
+	FloatingEvents,
+	FloatingNodeType,
+	FloatingRootContext,
+	FloatingStyles,
+	FloatingTreeType,
+	HandleClose,
+	HandleCloseContext,
+	HTMLProps,
+	MutableRefObject,
+	NarrowedElement,
+	OpenChangeReason,
+	RefCallback,
+	ReferenceType,
+	SafePolygonOptions,
+	UseFloatingData,
+	UseFloatingOptions,
+	UseFloatingReturn,
+	UseFloatingRootContextOptions,
+	UseInteractionsReturn,
+	UsePositionFloatingData,
+	UsePositionFloatingOptions,
+	UsePositionFloatingReturn,
+} from './types';
+
 // Positioning + context. The public `useFloating` (from ./context) wraps the
 // positioning core and returns the interaction `context`.
 export { useFloating, useFloatingRootContext, createPubSub } from './context';
@@ -54,6 +134,15 @@ export { useListNavigation } from './useListNavigation';
 export { useTypeahead } from './useTypeahead';
 export { useHover } from './useHover';
 export { safePolygon } from './safePolygon';
+// Interaction-hook prop types (mirror upstream @floating-ui/react's names).
+export type { UseRoleProps } from './useRole';
+export type { UseClickProps } from './useClick';
+export type { UseFocusProps } from './useFocus';
+export type { UseDismissProps } from './useDismiss';
+export type { UseClientPointProps } from './useClientPoint';
+export type { UseListNavigationProps } from './useListNavigation';
+export type { UseTypeaheadProps } from './useTypeahead';
+export type { UseHoverProps } from './useHover';
 
 // Components (phase 3 — in progress).
 export { FloatingOverlay } from './FloatingOverlay';
@@ -77,3 +166,22 @@ export {
 	useDelayGroupContext,
 	FloatingDelayGroupContext,
 } from './delayGroup';
+
+// Component / transition prop types (mirror upstream's exported names; the
+// octane adaptations — OctaneNode children, ref-as-prop, native events — are
+// documented on each type). FloatingListProps / UseListItemProps are exported
+// here even though upstream keeps them module-private, since octane bindings
+// compose them.
+export type { CompositeProps, CompositeItemProps } from './Composite';
+export type { FloatingArrowProps } from './FloatingArrow';
+export type { FloatingFocusManagerProps } from './FloatingFocusManager';
+export type { FloatingListProps, UseListItemProps } from './FloatingList';
+export type { FloatingOverlayProps } from './FloatingOverlay';
+export type { FloatingPortalProps, UseFloatingPortalNodeProps } from './FloatingPortal';
+export type { FloatingNodeProps, FloatingTreeProps } from './tree';
+export type {
+	TransitionStatus,
+	UseTransitionStatusProps,
+	UseTransitionStylesProps,
+} from './transitions';
+export type { FloatingDelayGroupProps } from './delayGroup';

package/src/pubsub.ts

@@ -1,6 +1,8 @@
 // The tiny event emitter shared by useFloatingRootContext and FloatingTree. Kept
 // in its own module so context.ts and tree.ts don't form an import cycle.
-export function createPubSub(): any {
+import type { FloatingEvents } from './types';
+
+export function createPubSub(): FloatingEvents {
 	const map = new Map<string, Set<(data: any) => void>>();
 	return {
 		emit(event: string, data: any) {

package/src/safePolygon.ts

@@ -4,6 +4,7 @@
 import { isElement } from '@floating-ui/utils/dom';
 
 import { clearTimeoutIfSet, contains, getNodeChildren, getTarget } from './utils';
+import type { HandleClose, HandleCloseContext, SafePolygonOptions } from './types';
 
 function isPointInPolygon(point: number[], polygon: number[][]): boolean {
 	const [x, y] = point;
@@ -19,7 +20,10 @@ function isPointInPolygon(point: number[], polygon: number[][]): boolean {
 	}
 	return isInsideResult;
 }
-function isInside(point: number[], rect: any): boolean {
+function isInside(
+	point: number[],
+	rect: { x: number; y: number; width: number; height: number },
+): boolean {
 	return (
 		point[0] >= rect.x &&
 		point[0] <= rect.x + rect.width &&
@@ -28,7 +32,12 @@ function isInside(point: number[], rect: any): boolean {
 	);
 }
 
-export function safePolygon(options: any = {}): any {
+/**
+ * Generates a safe polygon area that the user can traverse without closing the
+ * floating element once leaving the reference element.
+ * @see https://floating-ui.com/docs/useHover#safepolygon
+ */
+export function safePolygon(options: SafePolygonOptions = {}): HandleClose {
 	const { buffer = 0.5, blockPointerEvents = false, requireIntent = true } = options;
 
 	const timeoutRef = { current: -1 };
@@ -56,9 +65,9 @@ export function safePolygon(options: any = {}): any {
 		return speed;
 	}
 
-	const fn = (_ref: any) => {
+	const fn: HandleClose = (_ref: HandleCloseContext) => {
 		const { x, y, placement, elements, onClose, nodeId, tree } = _ref;
-		return function onMouseMove(event: any) {
+		return function onMouseMove(event: MouseEvent) {
 			function close() {
 				clearTimeoutIfSet(timeoutRef);
 				onClose();

package/src/transitions.ts

@@ -2,6 +2,7 @@
 // internal useDelayUnmount) — placement-aware CSS-transition state/styles for a
 // floating element. ReactDOM.flushSync → octane flushSync.
 import { flushSync, useEffect, useMemo, useState } from 'octane';
+import type { Placement, Side } from '@floating-ui/dom';
 
 import { splitSlot, subSlot } from './internal';
 import {
@@ -9,7 +10,20 @@ import {
 	execWithArgsOrReturn,
 	useLatestRef,
 	useModernLayoutEffect,
+	type CSSProperties,
 } from './utils';
+import type { FloatingContext, ReferenceType } from './types';
+
+export type TransitionStatus = 'unmounted' | 'initial' | 'open' | 'close';
+
+type Duration = number | Partial<{ open: number; close: number }>;
+
+// Styles (or a side/placement-aware factory of styles) for one transition state.
+// Upstream's `CSSStylesProperty`, with `React.CSSProperties` → the octane style
+// object form.
+type CSSStylesProperty =
+	| CSSProperties
+	| ((params: { side: Side; placement: Placement }) => CSSProperties);
 
 function useDelayUnmount(open: boolean, durationMs: number, slot: symbol | undefined): boolean {
 	const [isMounted, setIsMounted] = useState(open, subSlot(slot, 'mounted'));
@@ -29,10 +43,31 @@ function useDelayUnmount(open: boolean, durationMs: number, slot: symbol | undef
 	return isMounted;
 }
 
-export function useTransitionStatus(...args: any[]): any {
+export interface UseTransitionStatusProps {
+	/**
+	 * The duration of the transition in milliseconds, or an object containing
+	 * `open` and `close` keys for different durations.
+	 */
+	duration?: Duration;
+}
+
+/**
+ * Provides a status string to apply CSS transitions to a floating element,
+ * correctly handling placement-aware transitions.
+ * @see https://floating-ui.com/docs/useTransition#usetransitionstatus
+ */
+export function useTransitionStatus(
+	context: FloatingContext,
+	props?: UseTransitionStatusProps,
+	slot?: symbol,
+): { isMounted: boolean; status: TransitionStatus };
+export function useTransitionStatus(...args: any[]): {
+	isMounted: boolean;
+	status: TransitionStatus;
+} {
 	const [user, slot] = splitSlot(args);
-	const context = user[0];
-	const props = (user[1] as any) ?? {};
+	const context = user[0] as FloatingContext;
+	const props = (user[1] as UseTransitionStatusProps) ?? {};
 
 	const open = context.open;
 	const floating = context.elements.floating;
@@ -40,7 +75,7 @@ export function useTransitionStatus(...args: any[]): any {
 
 	const isNumberDuration = typeof duration === 'number';
 	const closeDuration = (isNumberDuration ? duration : duration.close) || 0;
-	const [status, setStatus] = useState('unmounted', subSlot(slot, 'status'));
+	const [status, setStatus] = useState<TransitionStatus>('unmounted', subSlot(slot, 'status'));
 	const isMounted = useDelayUnmount(open, closeDuration, subSlot(slot, 'unmount'));
 	if (!isMounted && status === 'close') {
 		setStatus('unmounted');
@@ -71,10 +106,41 @@ export function useTransitionStatus(...args: any[]): any {
 	return { isMounted, status };
 }
 
-export function useTransitionStyles(...args: any[]): any {
+export interface UseTransitionStylesProps extends UseTransitionStatusProps {
+	/**
+	 * The styles to apply when the floating element is initially mounted.
+	 */
+	initial?: CSSStylesProperty;
+	/**
+	 * The styles to apply when the floating element is transitioning to the
+	 * `open` state.
+	 */
+	open?: CSSStylesProperty;
+	/**
+	 * The styles to apply when the floating element is transitioning to the
+	 * `close` state.
+	 */
+	close?: CSSStylesProperty;
+	/**
+	 * The styles to apply to all states.
+	 */
+	common?: CSSStylesProperty;
+}
+
+/**
+ * Provides styles to apply CSS transitions to a floating element, correctly
+ * handling placement-aware transitions. Wrapper around `useTransitionStatus`.
+ * @see https://floating-ui.com/docs/useTransition#usetransitionstyles
+ */
+export function useTransitionStyles<RT extends ReferenceType = ReferenceType>(
+	context: FloatingContext<RT>,
+	props?: UseTransitionStylesProps,
+	slot?: symbol,
+): { isMounted: boolean; styles: CSSProperties };
+export function useTransitionStyles(...args: any[]): { isMounted: boolean; styles: CSSProperties } {
 	const [user, slot] = splitSlot(args);
-	const context = user[0];
-	const props = (user[1] as any) ?? {};
+	const context = user[0] as FloatingContext;
+	const props = (user[1] as UseTransitionStylesProps) ?? {};
 
 	const unstableInitial = props.initial ?? { opacity: 0 };
 	const unstableOpen = props.open;
@@ -83,13 +149,13 @@ export function useTransitionStyles(...args: any[]): any {
 	const duration = props.duration ?? 250;
 
 	const placement = context.placement;
-	const side = placement.split('-')[0];
+	const side = placement.split('-')[0] as Side;
 	const fnArgs = useMemo(() => ({ side, placement }), [side, placement], subSlot(slot, 'args'));
 	const isNumberDuration = typeof duration === 'number';
 	const openDuration = (isNumberDuration ? duration : duration.open) || 0;
 	const closeDuration = (isNumberDuration ? duration : duration.close) || 0;
 
-	const [styles, setStyles] = useState(
+	const [styles, setStyles] = useState<CSSProperties>(
 		() => ({
 			...execWithArgsOrReturn(unstableCommon, fnArgs),
 			...execWithArgsOrReturn(unstableInitial, fnArgs),
@@ -114,7 +180,7 @@ export function useTransitionStyles(...args: any[]): any {
 					return acc;
 				}, {});
 			if (status === 'initial') {
-				setStyles((s: any) => ({
+				setStyles((s) => ({
 					transitionProperty: s.transitionProperty,
 					...commonStyles,
 					...initialStyles,

package/src/tree.ts

@@ -10,26 +10,50 @@ import {
 	useRef,
 	useState,
 } from 'octane';
+import type { OctaneNode } from 'octane';
 
 import { createPubSub } from './pubsub';
 import { S, splitSlot, subSlot } from './internal';
 import { useId } from './useId';
 import { useModernLayoutEffect } from './utils';
+import type { FloatingNodeType, FloatingTreeType, ReferenceType } from './types';
 
-export const FloatingNodeContext = createContext<any>(null);
-export const FloatingTreeContext = createContext<any>(null);
+interface FloatingNodeContextValue {
+	id: string | undefined;
+	parentId: string | null;
+}
+
+export const FloatingNodeContext = createContext<FloatingNodeContextValue | null>(null);
+export const FloatingTreeContext = 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 => {
 	const context = useContext(FloatingNodeContext);
-	return context ? context.id : null;
+	// A FloatingNode's `id` may be undefined (upstream allows it); the public
+	// contract is `string | null`, so coalesce.
+	return context ? (context.id ?? null) : null;
 };
 
-export const useFloatingTree = (): any => useContext(FloatingTreeContext);
+/**
+ * Returns the nearest floating tree context, if available.
+ */
+export const useFloatingTree = <
+	RT extends ReferenceType = ReferenceType,
+>(): FloatingTreeType<RT> | null => useContext(FloatingTreeContext) as FloatingTreeType<RT> | null;
 
+/**
+ * Registers a node into the `FloatingTree`, returning its id.
+ * @see https://floating-ui.com/docs/FloatingTree
+ */
+export function useFloatingNodeId(customParentId?: string, slot?: symbol): string;
+export function useFloatingNodeId(slot?: symbol): string;
 export function useFloatingNodeId(...args: any[]): string {
 	const [user, slotArg] = splitSlot(args);
 	const slot = slotArg ?? S('useFloatingNodeId');
-	const customParentId = user[0];
+	const customParentId = user[0] as string | undefined;
 
 	const id = useId(subSlot(slot, 'id'));
 	const tree = useFloatingTree();
@@ -50,7 +74,16 @@ export function useFloatingNodeId(...args: any[]): string {
 	return id;
 }
 
-export function FloatingNode(props: any): any {
+export interface FloatingNodeProps {
+	children?: OctaneNode;
+	id: string | undefined;
+}
+
+/**
+ * Provides parent node context for nested floating elements.
+ * @see https://floating-ui.com/docs/FloatingTree
+ */
+export function FloatingNode(props: FloatingNodeProps): OctaneNode {
 	const children = props.children;
 	const id = props.id;
 	const parentId = useFloatingParentNodeId();
@@ -58,25 +91,34 @@ export function FloatingNode(props: any): any {
 	return createElement(FloatingNodeContext.Provider, { value, children });
 }
 
-export function FloatingTree(props: any): any {
+export interface FloatingTreeProps {
+	children?: OctaneNode;
+}
+
+/**
+ * Provides context for nested floating elements when they are not children of
+ * each other on the DOM.
+ * @see https://floating-ui.com/docs/FloatingTree
+ */
+export function FloatingTree(props: FloatingTreeProps): OctaneNode {
 	const children = props.children;
-	const nodesRef = useRef<any[]>([], S('FloatingTree:nodes'));
+	const nodesRef = useRef<FloatingNodeType[]>([], S('FloatingTree:nodes'));
 	const addNode = useCallback(
-		(node: any) => {
+		(node: FloatingNodeType) => {
 			nodesRef.current = [...nodesRef.current, node];
 		},
 		[],
 		S('FloatingTree:add'),
 	);
 	const removeNode = useCallback(
-		(node: any) => {
+		(node: FloatingNodeType) => {
 			nodesRef.current = nodesRef.current.filter((n) => n !== node);
 		},
 		[],
 		S('FloatingTree:remove'),
 	);
 	const [events] = useState(() => createPubSub(), S('FloatingTree:events'));
-	const value = useMemo(
+	const value = useMemo<FloatingTreeType>(
 		() => ({ nodesRef, addNode, removeNode, events }),
 		[addNode, removeNode, events],
 		S('FloatingTree:value'),