@octanejs/floating-ui 0.1.9 → 0.1.10

package/src/types.ts

@@ -0,0 +1,337 @@
+// Shared public types for @octanejs/floating-ui — the octane adaptation of
+// @floating-ui/react's (0.27.19) type surface. Names and shapes mirror upstream;
+// React idioms map to the port's actual contract:
+//
+//  - `React.MutableRefObject<T>` → octane's plain mutable ref object
+//    (`MutableRefObject<T>` below — `{ current: T }`, what octane's useRef
+//    returns). Ref callbacks are `(node: T | null) => void` with an optional
+//    React-19-style cleanup return.
+//  - `React.SetStateAction` / `Dispatch` → octane's useState setter shape
+//    (`(value: T | ((prev: T) => T)) => void`).
+//  - `React.HTMLProps<T>` prop bags → `HTMLProps<T>`: octane's JSX attribute
+//    surface (`Octane.HTMLAttributes` — NATIVE event handlers, no synthetic
+//    layer) plus an open string index, because the interaction prop getters
+//    merge arbitrary keys (aria-*, data-*, ref).
+//  - `whileElementsMounted` may return `void` as well as a cleanup — the port
+//    forwards its result straight to an octane effect, which accepts both.
+import type { Octane } from 'octane/jsx-runtime';
+import type {
+	ComputePositionConfig,
+	ComputePositionReturn,
+	Padding,
+	Strategy,
+	VirtualElement,
+} from '@floating-ui/dom';
+
+type Prettify<T> = {
+	[K in keyof T]: T[K];
+} & {};
+
+export type ReferenceType = Element | VirtualElement;
+
+export type NarrowedElement<T> = T extends Element ? T : Element;
+
+/** Octane ref-object shape (what octane's `useRef` returns). */
+export interface MutableRefObject<T> {
+	current: T;
+}
+
+/** Octane ref callback (React-19 style: may return a cleanup). */
+export type RefCallback<T> = (node: T | null) => void | (() => void);
+
+export type OpenChangeReason =
+	| 'outside-press'
+	| 'escape-key'
+	| 'ancestor-scroll'
+	| 'reference-press'
+	| 'click'
+	| 'hover'
+	| 'focus'
+	| 'focus-out'
+	| 'list-navigation'
+	| 'safe-polygon';
+
+export interface FloatingEvents {
+	emit<T extends string>(event: T, data?: any): void;
+	on(event: string, handler: (data: any) => void): void;
+	off(event: string, handler: (data: any) => void): void;
+}
+
+export interface ContextData {
+	openEvent?: Event;
+	floatingContext?: FloatingContext;
+	/** @deprecated use `onTypingChange` prop in `useTypeahead` */
+	typing?: boolean;
+	[key: string]: any;
+}
+
+/**
+ * The pre-configured positioning styles for the floating element. Upstream
+ * types this as `React.CSSProperties`; the port returns exactly this object
+ * shape, which is assignable to octane's `style` prop.
+ */
+export interface FloatingStyles {
+	position: Strategy;
+	top: number;
+	left: number;
+	transform?: string;
+	willChange?: string;
+}
+
+// ─── Positioning core (the @floating-ui/react-dom `useFloating` surface) ─────
+
+export type UsePositionFloatingOptions<RT extends ReferenceType = ReferenceType> = Prettify<
+	Partial<ComputePositionConfig> & {
+		/**
+		 * A callback invoked when both the reference and floating elements are
+		 * mounted, and cleaned up when either is unmounted. This is useful for
+		 * setting up event listeners (e.g. pass `autoUpdate`).
+		 */
+		whileElementsMounted?: (
+			reference: RT,
+			floating: HTMLElement,
+			update: () => void,
+		) => void | (() => void);
+		/**
+		 * Object containing the reference and floating elements.
+		 */
+		elements?: {
+			reference?: RT | null;
+			floating?: HTMLElement | null;
+		};
+		/**
+		 * The `open` state of the floating element to synchronize with the
+		 * `isPositioned` value.
+		 * @default false
+		 */
+		open?: boolean;
+		/**
+		 * Whether to use `transform` for positioning instead of `top` and `left`
+		 * (layout) in the `floatingStyles` object.
+		 * @default true
+		 */
+		transform?: boolean;
+	}
+>;
+
+export type UsePositionFloatingData = Prettify<ComputePositionReturn & { isPositioned: boolean }>;
+
+export type UsePositionFloatingReturn<RT extends ReferenceType = ReferenceType> = Prettify<
+	UsePositionFloatingData & {
+		/**
+		 * Update the position of the floating element, re-rendering the component
+		 * if required.
+		 */
+		update: () => void;
+		/**
+		 * Pre-configured positioning styles to apply to the floating element.
+		 */
+		floatingStyles: FloatingStyles;
+		/**
+		 * Object containing the reference and floating refs and reactive setters.
+		 */
+		refs: {
+			reference: MutableRefObject<RT | null>;
+			floating: MutableRefObject<HTMLElement | null>;
+			setReference: (node: RT | null) => void;
+			setFloating: (node: HTMLElement | null) => void;
+		};
+		/**
+		 * Object containing the reference and floating elements.
+		 */
+		elements: {
+			reference: RT | null;
+			floating: HTMLElement | null;
+		};
+	}
+>;
+
+/** Options for the ref-aware `arrow` middleware (accepts an octane ref or an element). */
+export interface ArrowOptions {
+	/**
+	 * The arrow element to be positioned.
+	 * @default undefined
+	 */
+	element: MutableRefObject<Element | null> | Element | null;
+	/**
+	 * The padding between the arrow element and the floating element edges.
+	 * Useful when the floating element has rounded corners.
+	 * @default 0
+	 */
+	padding?: Padding;
+}
+
+// ─── Interaction context (the @floating-ui/react `useFloating` surface) ──────
+
+export interface ExtendedRefs<RT> {
+	reference: MutableRefObject<ReferenceType | null>;
+	floating: MutableRefObject<HTMLElement | null>;
+	domReference: MutableRefObject<NarrowedElement<RT> | null>;
+	setReference(node: RT | null): void;
+	setFloating(node: HTMLElement | null): void;
+	setPositionReference(node: ReferenceType | null): void;
+}
+
+export interface ExtendedElements<RT> {
+	reference: ReferenceType | null;
+	floating: HTMLElement | null;
+	domReference: NarrowedElement<RT> | null;
+}
+
+export type FloatingContext<RT extends ReferenceType = ReferenceType> = Omit<
+	UsePositionFloatingReturn<RT>,
+	'refs' | 'elements'
+> & {
+	open: boolean;
+	onOpenChange(open: boolean, event?: Event, reason?: OpenChangeReason): void;
+	events: FloatingEvents;
+	dataRef: MutableRefObject<ContextData>;
+	nodeId: string | undefined;
+	floatingId: string;
+	refs: ExtendedRefs<RT>;
+	elements: ExtendedElements<RT>;
+};
+
+export interface FloatingRootContext<RT extends ReferenceType = ReferenceType> {
+	dataRef: MutableRefObject<ContextData>;
+	open: boolean;
+	onOpenChange: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
+	elements: {
+		domReference: Element | null;
+		reference: RT | null;
+		floating: HTMLElement | null;
+	};
+	events: FloatingEvents;
+	floatingId: string;
+	refs: {
+		setPositionReference(node: ReferenceType | null): void;
+	};
+}
+
+export interface UseFloatingRootContextOptions {
+	open?: boolean;
+	onOpenChange?: (open: boolean, event?: Event, reason?: OpenChangeReason) => void;
+	elements: {
+		reference: Element | null;
+		floating: HTMLElement | null;
+	};
+}
+
+export interface UseFloatingOptions<RT extends ReferenceType = ReferenceType> extends Omit<
+	UsePositionFloatingOptions<RT>,
+	'elements'
+> {
+	rootContext?: FloatingRootContext<RT>;
+	/**
+	 * Object of external elements as an alternative to the `refs` object setters.
+	 */
+	elements?: {
+		/**
+		 * Externally passed reference element. Store in state.
+		 */
+		reference?: Element | null;
+		/**
+		 * Externally passed floating element. Store in state.
+		 */
+		floating?: HTMLElement | null;
+	};
+	/**
+	 * An event callback that is invoked when the floating element is opened or
+	 * closed.
+	 */
+	onOpenChange?(open: boolean, event?: Event, reason?: OpenChangeReason): void;
+	/**
+	 * Unique node id when using `FloatingTree`.
+	 */
+	nodeId?: string;
+}
+
+export type UseFloatingReturn<RT extends ReferenceType = ReferenceType> = Prettify<
+	Omit<UsePositionFloatingReturn<RT>, 'refs' | 'elements'> & {
+		/**
+		 * `FloatingContext`
+		 */
+		context: Prettify<FloatingContext<RT>>;
+		/**
+		 * Object containing the reference and floating refs and reactive setters.
+		 */
+		refs: ExtendedRefs<RT>;
+		elements: ExtendedElements<RT>;
+	}
+>;
+
+export type UseFloatingData = Prettify<UseFloatingReturn>;
+
+// ─── Interaction prop getters (useInteractions) ──────────────────────────────
+
+/**
+ * An octane HTML prop bag: octane's JSX attribute surface (NATIVE event
+ * handlers — octane has no synthetic events) plus an open string index, since
+ * the interaction hooks and prop getters merge arbitrary keys (aria-*, data-*,
+ * ref). The octane analog of upstream's `React.HTMLProps<T>`.
+ */
+export type HTMLProps<T extends EventTarget = HTMLElement> = Octane.HTMLAttributes<T> & {
+	[key: string]: unknown;
+};
+
+export interface ExtendedUserProps {
+	active?: boolean;
+	selected?: boolean;
+}
+
+export interface ElementProps {
+	reference?: HTMLProps<Element>;
+	floating?: HTMLProps<HTMLElement>;
+	item?: HTMLProps<HTMLElement> | ((props: ExtendedUserProps) => HTMLProps<HTMLElement>);
+}
+
+export interface UseInteractionsReturn {
+	// The `| object` widening keeps prop bags typed against other libraries'
+	// HTML prop shapes (e.g. React's) callable — the getters merge any object.
+	getReferenceProps: (userProps?: HTMLProps<Element> | object) => Record<string, unknown>;
+	getFloatingProps: (userProps?: HTMLProps<HTMLElement> | object) => Record<string, unknown>;
+	getItemProps: (
+		userProps?: (Omit<HTMLProps<HTMLElement>, 'selected' | 'active'> & ExtendedUserProps) | object,
+	) => Record<string, unknown>;
+}
+
+// ─── Tree ────────────────────────────────────────────────────────────────────
+
+export interface FloatingNodeType<RT extends ReferenceType = ReferenceType> {
+	id: string | undefined;
+	parentId: string | null;
+	context?: FloatingContext<RT>;
+}
+
+export interface FloatingTreeType<RT extends ReferenceType = ReferenceType> {
+	nodesRef: MutableRefObject<Array<FloatingNodeType<RT>>>;
+	events: FloatingEvents;
+	addNode(node: FloatingNodeType): void;
+	removeNode(node: FloatingNodeType): void;
+}
+
+// ─── Shared interaction-hook types ───────────────────────────────────────────
+
+export type Delay =
+	| number
+	| Partial<{
+			open: number;
+			close: number;
+	  }>;
+
+export interface SafePolygonOptions {
+	buffer?: number;
+	blockPointerEvents?: boolean;
+	requireIntent?: boolean;
+}
+
+export interface HandleCloseContext extends FloatingContext {
+	onClose: () => void;
+	tree?: FloatingTreeType | null;
+	leave?: boolean;
+}
+
+export interface HandleClose {
+	(context: HandleCloseContext): (event: MouseEvent) => void;
+	__options?: SafePolygonOptions;
+}

package/src/useClick.ts

@@ -5,21 +5,71 @@ import { useMemo, useRef } from 'octane';
 
 import { splitSlot, subSlot } from './internal';
 import { isMouseLikePointerType, isTypeableElement } from './utils';
+import type { ElementProps, FloatingRootContext } from './types';
 
-function isButtonTarget(event: any): boolean {
+export interface UseClickProps {
+	/**
+	 * Whether the Hook is enabled, including all internal Effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean;
+	/**
+	 * The type of event to use to determine a “click” with mouse input.
+	 * Keyboard clicks work as normal.
+	 * @default 'click'
+	 */
+	event?: 'click' | 'mousedown';
+	/**
+	 * Whether to toggle the open state with repeated clicks.
+	 * @default true
+	 */
+	toggle?: boolean;
+	/**
+	 * Whether to ignore the logic for mouse input (for example, if `useHover()`
+	 * is also being used).
+	 * @default false
+	 */
+	ignoreMouse?: boolean;
+	/**
+	 * Whether to add keyboard handlers (Enter and Space key functionality) for
+	 * non-button elements (to open/close the floating element via keyboard
+	 * “click”).
+	 * @default true
+	 */
+	keyboardHandlers?: boolean;
+	/**
+	 * If already open from another event such as the `useHover()` Hook,
+	 * determines whether to keep the floating element open when clicking the
+	 * reference element for the first time.
+	 * @default true
+	 */
+	stickIfOpen?: boolean;
+}
+
+function isButtonTarget(event: Event): boolean {
 	return isHTMLElement(event.target) && event.target.tagName === 'BUTTON';
 }
-function isAnchorTarget(event: any): boolean {
+function isAnchorTarget(event: Event): boolean {
 	return isHTMLElement(event.target) && event.target.tagName === 'A';
 }
-function isSpaceIgnored(element: any): boolean {
+function isSpaceIgnored(element: Element | null): boolean {
 	return isTypeableElement(element);
 }
 
-export function useClick(...args: any[]): any {
+/**
+ * Opens or closes the floating element when clicking the reference element.
+ * @see https://floating-ui.com/docs/useClick
+ */
+export function useClick(
+	context: FloatingRootContext,
+	props?: UseClickProps,
+	slot?: symbol,
+): ElementProps;
+export function useClick(...args: any[]): ElementProps {
 	const [user, slot] = splitSlot(args);
-	const context = user[0];
-	const props = (user[1] as any) ?? {};
+	const context = user[0] as FloatingRootContext;
+	const props = (user[1] as UseClickProps) ?? {};
 
 	const open = context.open;
 	const onOpenChange = context.onOpenChange;
@@ -33,15 +83,15 @@ export function useClick(...args: any[]): any {
 	const keyboardHandlers = props.keyboardHandlers ?? true;
 	const stickIfOpen = props.stickIfOpen ?? true;
 
-	const pointerTypeRef = useRef<any>(undefined, subSlot(slot, 'ptype'));
+	const pointerTypeRef = useRef<string | undefined>(undefined, subSlot(slot, 'ptype'));
 	const didKeyDownRef = useRef(false, subSlot(slot, 'kd'));
 
 	const reference = useMemo(
 		() => ({
-			onPointerDown(event: any) {
+			onPointerDown(event: PointerEvent) {
 				pointerTypeRef.current = event.pointerType;
 			},
-			onMouseDown(event: any) {
+			onMouseDown(event: MouseEvent) {
 				const pointerType = pointerTypeRef.current;
 				if (event.button !== 0) return;
 				if (eventOption === 'click') return;
@@ -59,7 +109,7 @@ export function useClick(...args: any[]): any {
 					onOpenChange(true, event, 'click');
 				}
 			},
-			onClick(event: any) {
+			onClick(event: MouseEvent) {
 				const pointerType = pointerTypeRef.current;
 				if (eventOption === 'mousedown' && pointerTypeRef.current) {
 					pointerTypeRef.current = undefined;
@@ -78,7 +128,7 @@ export function useClick(...args: any[]): any {
 					onOpenChange(true, event, 'click');
 				}
 			},
-			onKeyDown(event: any) {
+			onKeyDown(event: KeyboardEvent) {
 				pointerTypeRef.current = undefined;
 				if (event.defaultPrevented || !keyboardHandlers || isButtonTarget(event)) {
 					return;
@@ -98,7 +148,7 @@ export function useClick(...args: any[]): any {
 					}
 				}
 			},
-			onKeyUp(event: any) {
+			onKeyUp(event: KeyboardEvent) {
 				if (
 					event.defaultPrevented ||
 					!keyboardHandlers ||
@@ -131,7 +181,7 @@ export function useClick(...args: any[]): any {
 		subSlot(slot, 'm:ref'),
 	);
 
-	return useMemo(
+	return useMemo<ElementProps>(
 		() => (enabled ? { reference } : {}),
 		[enabled, reference],
 		subSlot(slot, 'm:ret'),

package/src/useClientPoint.ts

@@ -11,6 +11,33 @@ import {
 	useEffectEvent,
 	useModernLayoutEffect,
 } from './utils';
+import type { ElementProps, FloatingRootContext } from './types';
+
+export interface UseClientPointProps {
+	/**
+	 * Whether the Hook is enabled, including all internal Effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean;
+	/**
+	 * Whether to restrict the client point to an axis and use the reference
+	 * element (if it exists) as the other axis. This can be useful if the
+	 * floating element is also interactive.
+	 * @default 'both'
+	 */
+	axis?: 'x' | 'y' | 'both';
+	/**
+	 * An explicitly defined `x` client coordinate.
+	 * @default null
+	 */
+	x?: number | null;
+	/**
+	 * An explicitly defined `y` client coordinate.
+	 * @default null
+	 */
+	y?: number | null;
+}
 
 function createVirtualElement(domElement: any, data: any): any {
 	let offsetX: number | null = null;
@@ -57,10 +84,20 @@ function isMouseBasedEvent(event: any): boolean {
 	return event != null && event.clientX != null;
 }
 
-export function useClientPoint(...args: any[]): any {
+/**
+ * Positions the floating element relative to a client point (in the viewport),
+ * such as the mouse position. By default, it follows the mouse cursor.
+ * @see https://floating-ui.com/docs/useClientPoint
+ */
+export function useClientPoint(
+	context: FloatingRootContext,
+	props?: UseClientPointProps,
+	slot?: symbol,
+): ElementProps;
+export function useClientPoint(...args: any[]): ElementProps {
 	const [user, slot] = splitSlot(args);
-	const context = user[0];
-	const props = (user[1] as any) ?? {};
+	const context = user[0] as FloatingRootContext;
+	const props = (user[1] as UseClientPointProps) ?? {};
 
 	const open = context.open;
 	const dataRef = context.dataRef;
@@ -74,12 +111,15 @@ export function useClientPoint(...args: any[]): any {
 	const y = props.y ?? null;
 
 	const initialRef = useRef(false, subSlot(slot, 'init'));
-	const cleanupListenerRef = useRef<any>(null, subSlot(slot, 'cleanup'));
-	const [pointerType, setPointerType] = useState<any>(undefined, subSlot(slot, 'ptype'));
+	const cleanupListenerRef = useRef<(() => void) | null>(null, subSlot(slot, 'cleanup'));
+	const [pointerType, setPointerType] = useState<string | undefined>(
+		undefined,
+		subSlot(slot, 'ptype'),
+	);
 	const [reactive, setReactive] = useState<any[]>([], subSlot(slot, 'reactive'));
 
 	const setReference = useEffectEvent(
-		(px: number, py: number) => {
+		(px: number | null, py: number | null) => {
 			if (initialRef.current) return;
 			if (dataRef.current.openEvent && !isMouseBasedEvent(dataRef.current.openEvent)) {
 				return;
@@ -92,7 +132,7 @@ export function useClientPoint(...args: any[]): any {
 	);
 
 	const handleReferenceEnterOrMove = useEffectEvent(
-		(event: any) => {
+		(event: MouseEvent) => {
 			if (x != null || y != null) return;
 			if (!open) {
 				setReference(event.clientX, event.clientY);
@@ -108,7 +148,7 @@ export function useClientPoint(...args: any[]): any {
 		() => {
 			if (!openCheck || !enabled || x != null || y != null) return;
 			const win = getWindow(floating);
-			function handleMouseMove(event: any) {
+			function handleMouseMove(event: MouseEvent) {
 				const target = getTarget(event);
 				if (!contains(floating, target as any)) {
 					setReference(event.clientX, event.clientY);
@@ -170,7 +210,7 @@ export function useClientPoint(...args: any[]): any {
 
 	const reference = useMemo(
 		() => {
-			function setPointerTypeRef(_ref: any) {
+			function setPointerTypeRef(_ref: PointerEvent) {
 				const { pointerType: pt } = _ref;
 				setPointerType(pt);
 			}
@@ -185,7 +225,7 @@ export function useClientPoint(...args: any[]): any {
 		subSlot(slot, 'm:ref'),
 	);
 
-	return useMemo(
+	return useMemo<ElementProps>(
 		() => (enabled ? { reference } : {}),
 		[enabled, reference],
 		subSlot(slot, 'm:ret'),