@octanejs/floating-ui 0.1.9 → 0.1.10

package/src/useListNavigation.ts

@@ -30,6 +30,150 @@ import {
 	useLatestRef,
 	useModernLayoutEffect,
 } from './utils';
+import type { Dimensions } from '@floating-ui/dom';
+import type { ElementProps, FloatingRootContext, MutableRefObject } from './types';
+
+export interface UseListNavigationProps {
+	/**
+	 * A ref that holds an array of list items.
+	 * @default empty list
+	 */
+	listRef: MutableRefObject<Array<HTMLElement | null>>;
+	/**
+	 * The index of the currently active (focused or highlighted) item, which may
+	 * or may not be selected.
+	 * @default null
+	 */
+	activeIndex: number | null;
+	/**
+	 * A callback that is called when the user navigates to a new active item,
+	 * passed in a new `activeIndex`.
+	 */
+	onNavigate?: (activeIndex: number | null) => void;
+	/**
+	 * Whether the Hook is enabled, including all internal Effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean;
+	/**
+	 * The currently selected item index, which may or may not be active.
+	 * @default null
+	 */
+	selectedIndex?: number | null;
+	/**
+	 * Whether to focus the item upon opening the floating element. 'auto' infers
+	 * what to do based on the input type (keyboard vs. pointer), while a boolean
+	 * value will force the value.
+	 * @default 'auto'
+	 */
+	focusItemOnOpen?: boolean | 'auto';
+	/**
+	 * Whether hovering an item synchronizes the focus.
+	 * @default true
+	 */
+	focusItemOnHover?: boolean;
+	/**
+	 * Whether pressing an arrow key on the navigation’s main axis opens the
+	 * floating element.
+	 * @default true
+	 */
+	openOnArrowKeyDown?: boolean;
+	/**
+	 * By default elements with either a `disabled` or `aria-disabled` attribute
+	 * are skipped in the list navigation — however, this requires the items to
+	 * be rendered.
+	 * This prop allows you to manually specify indices which should be disabled,
+	 * overriding the default logic.
+	 * For Windows-style select menus, where the menu does not open when
+	 * navigating via arrow keys, specify an empty array.
+	 * @default undefined
+	 */
+	disabledIndices?: Array<number> | ((index: number) => boolean);
+	/**
+	 * Determines whether focus can escape the list, such that nothing is selected
+	 * after navigating beyond the boundary of the list. In some
+	 * autocomplete/combobox components, this may be desired, as screen
+	 * readers will return to the input.
+	 * `loop` must be `true`.
+	 * @default false
+	 */
+	allowEscape?: boolean;
+	/**
+	 * Determines whether focus should loop around when navigating past the first
+	 * or last item.
+	 * @default false
+	 */
+	loop?: boolean;
+	/**
+	 * If the list is nested within another one (e.g. a nested submenu), the
+	 * navigation semantics change.
+	 * @default false
+	 */
+	nested?: boolean;
+	/**
+	 * Allows to specify the orientation of the parent list, which is used to
+	 * determine the direction of the navigation.
+	 * This is useful when list navigation is used within a Composite,
+	 * as the hook can't determine the orientation of the parent list automatically.
+	 */
+	parentOrientation?: UseListNavigationProps['orientation'];
+	/**
+	 * Whether the direction of the floating element’s navigation is in RTL
+	 * layout.
+	 * @default false
+	 */
+	rtl?: boolean;
+	/**
+	 * Whether the focus is virtual (using `aria-activedescendant`).
+	 * Use this if you need focus to remain on the reference element
+	 * (such as an input), but allow arrow keys to navigate list items.
+	 * This is common in autocomplete listbox components.
+	 * Your virtually-focused list items must have a unique `id` set on them.
+	 * If you’re using a component role with the `useRole()` Hook, then an `id` is
+	 * generated automatically.
+	 * @default false
+	 */
+	virtual?: boolean;
+	/**
+	 * The orientation in which navigation occurs.
+	 * @default 'vertical'
+	 */
+	orientation?: 'vertical' | 'horizontal' | 'both';
+	/**
+	 * Specifies how many columns the list has (i.e., it’s a grid). Use an
+	 * orientation of 'horizontal' (e.g. for an emoji picker/date picker, where
+	 * pressing ArrowRight or ArrowLeft can change rows), or 'both' (where the
+	 * current row cannot be escaped with ArrowRight or ArrowLeft, only ArrowUp
+	 * and ArrowDown).
+	 * @default 1
+	 */
+	cols?: number;
+	/**
+	 * Whether to scroll the active item into view when navigating. The default
+	 * value uses nearest options.
+	 */
+	scrollItemIntoView?: boolean | ScrollIntoViewOptions;
+	/**
+	 * When using virtual focus management, this holds a ref to the
+	 * virtually-focused item. This allows nested virtual navigation to be
+	 * enabled, and lets you know when a nested element is virtually focused from
+	 * the root reference handling the events. Requires `FloatingTree` to be
+	 * setup.
+	 */
+	virtualItemRef?: MutableRefObject<HTMLElement | null>;
+	/**
+	 * Only for `cols > 1`, specify sizes for grid items.
+	 * `{ width: 2, height: 2 }` means an item is 2 columns wide and 2 rows tall.
+	 */
+	itemSizes?: Dimensions[];
+	/**
+	 * Only relevant for `cols > 1` and items with different sizes, specify if
+	 * the grid is dense (as defined in the CSS spec for `grid-auto-flow`).
+	 * @default false
+	 */
+	dense?: boolean;
+}
 
 const ARROW_UP = 'ArrowUp';
 const ARROW_DOWN = 'ArrowDown';
@@ -73,10 +217,20 @@ function isCrossOrientationCloseKey(key: string, orientation: any, rtl: boolean,
 	return doSwitch(orientation, vertical, horizontal);
 }
 
-export function useListNavigation(...args: any[]): any {
+/**
+ * Adds arrow key-based navigation of a list of items, either using real DOM
+ * focus or virtual focus.
+ * @see https://floating-ui.com/docs/useListNavigation
+ */
+export function useListNavigation(
+	context: FloatingRootContext,
+	props: UseListNavigationProps,
+	slot?: symbol,
+): ElementProps;
+export function useListNavigation(...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 UseListNavigationProps) ?? {};
 
 	const open = context.open;
 	const onOpenChange = context.onOpenChange;
@@ -128,7 +282,7 @@ export function useListNavigation(...args: any[]): any {
 	const typeableComboboxReference = isTypeableCombobox(elements.domReference);
 	const focusItemOnOpenRef = useRef(focusItemOnOpen, subSlot(slot, 'fioo'));
 	const indexRef = useRef(selectedIndex != null ? selectedIndex : -1, subSlot(slot, 'index'));
-	const keyRef = useRef<any>(null, subSlot(slot, 'key'));
+	const keyRef = useRef<string | null>(null, subSlot(slot, 'key'));
 	const isPointerModalityRef = useRef(true, subSlot(slot, 'pm'));
 	const previousOnNavigateRef = useRef(onNavigate, subSlot(slot, 'ponav'));
 	const previousMountedRef = useRef(!!elements.floating, subSlot(slot, 'pmount'));
@@ -139,8 +293,8 @@ export function useListNavigation(...args: any[]): any {
 	const latestOpenRef = useLatestRef(open, subSlot(slot, 'lor'));
 	const scrollItemIntoViewRef = useLatestRef(scrollItemIntoView, subSlot(slot, 'siir'));
 	const selectedIndexRef = useLatestRef(selectedIndex, subSlot(slot, 'sir'));
-	const [activeId, setActiveId] = useState<any>(undefined, subSlot(slot, 'aid'));
-	const [virtualId, setVirtualId] = useState<any>(undefined, subSlot(slot, 'vid'));
+	const [activeId, setActiveId] = useState<string | undefined>(undefined, subSlot(slot, 'aid'));
+	const [virtualId, setVirtualId] = useState<string | undefined>(undefined, subSlot(slot, 'vid'));
 
 	const focusItem = useEffectEvent(
 		() => {
@@ -436,7 +590,7 @@ export function useListNavigation(...args: any[]): any {
 				const minGridIndex = cellMap.findIndex(
 					(index) => index != null && !isListIndexDisabled(listRef, index, disabledIndices),
 				);
-				const maxGridIndex = cellMap.reduce(
+				const maxGridIndex = cellMap.reduce<number>(
 					(foundIndex, index, cellIndex) =>
 						index != null && !isListIndexDisabled(listRef, index, disabledIndices)
 							? cellIndex
@@ -713,7 +867,7 @@ export function useListNavigation(...args: any[]): any {
 		subSlot(slot, 'm:ref'),
 	);
 
-	return useMemo(
+	return useMemo<ElementProps>(
 		() => (enabled ? { reference, floating, item } : {}),
 		[enabled, reference, floating, item],
 		subSlot(slot, 'm:ret'),

package/src/useMergeRefs.ts

@@ -3,12 +3,17 @@
 import { useCallback, useMemo, useRef } from 'octane';
 
 import { splitSlot, subSlot } from './internal';
+import type { MutableRefObject, RefCallback } from './types';
 
+export function useMergeRefs<Instance>(
+	refs: Array<MutableRefObject<Instance | null> | RefCallback<Instance> | null | undefined>,
+	slot?: symbol,
+): ((node: Instance | null) => void) | null;
 export function useMergeRefs(...args: any[]): any {
 	const [user, slot] = splitSlot(args);
 	const refs = (user[0] as any[]) ?? [];
 
-	const cleanupRef = useRef<any>(undefined, subSlot(slot, 'cleanup'));
+	const cleanupRef = useRef<(() => void) | undefined>(undefined, subSlot(slot, 'cleanup'));
 
 	const refEffect = useCallback(
 		(instance: any) => {

package/src/useRole.ts

@@ -7,17 +7,45 @@ import { splitSlot, subSlot } from './internal';
 import { useFloatingParentNodeId } from './tree';
 import { useId } from './useId';
 import { getFloatingFocusElement } from './utils';
+import type { ElementProps, ExtendedUserProps, FloatingRootContext, HTMLProps } from './types';
 
-const componentRoleToAriaRoleMap = new Map<string, string | false>([
+type AriaRole = 'tooltip' | 'dialog' | 'alertdialog' | 'menu' | 'listbox' | 'grid' | 'tree';
+type ComponentRole = 'select' | 'label' | 'combobox';
+
+export interface UseRoleProps {
+	/**
+	 * Whether the Hook is enabled, including all internal Effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean;
+	/**
+	 * The role of the floating element.
+	 * @default 'dialog'
+	 */
+	role?: AriaRole | ComponentRole;
+}
+
+const componentRoleToAriaRoleMap = new Map<AriaRole | ComponentRole, AriaRole | false>([
 	['select', 'listbox'],
 	['combobox', 'listbox'],
 	['label', false],
 ]);
 
-export function useRole(...args: any[]): any {
+/**
+ * Adds base screen reader props to the reference and floating elements for a
+ * given floating element `role`.
+ * @see https://floating-ui.com/docs/useRole
+ */
+export function useRole(
+	context: FloatingRootContext,
+	props?: UseRoleProps,
+	slot?: symbol,
+): ElementProps;
+export function useRole(...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 UseRoleProps) ?? {};
 
 	const open = context.open;
 	const elements = context.elements;
@@ -34,18 +62,19 @@ export function useRole(...args: any[]): any {
 		subSlot(slot, 'm:fid'),
 	);
 	const mapped = componentRoleToAriaRoleMap.get(role);
-	const ariaRole = mapped != null ? mapped : role;
+	// The map covers every ComponentRole, so the fallback `role` is an AriaRole.
+	const ariaRole = (mapped != null ? mapped : role) as AriaRole | false;
 	const parentId = useFloatingParentNodeId();
 	const isNested = parentId != null;
 
-	const reference = useMemo(
+	const reference = useMemo<HTMLProps<Element>>(
 		() => {
 			if (ariaRole === 'tooltip' || role === 'label') {
 				return {
 					['aria-' + (role === 'label' ? 'labelledby' : 'describedby')]: open
 						? floatingId
 						: undefined,
-				};
+				} as HTMLProps<Element>;
 			}
 			return {
 				'aria-expanded': open ? 'true' : 'false',
@@ -62,9 +91,9 @@ export function useRole(...args: any[]): any {
 		subSlot(slot, 'm:ref'),
 	);
 
-	const floating = useMemo(
+	const floating = useMemo<HTMLProps<HTMLElement>>(
 		() => {
-			const floatingProps: any = {
+			const floatingProps: HTMLProps<HTMLElement> = {
 				id: floatingId,
 				...(ariaRole && { role: ariaRole }),
 			};
@@ -81,9 +110,9 @@ export function useRole(...args: any[]): any {
 	);
 
 	const item = useCallback(
-		(_ref: any) => {
+		(_ref: ExtendedUserProps): HTMLProps<HTMLElement> => {
 			const { active, selected } = _ref;
-			const commonProps: any = {
+			const commonProps: HTMLProps<HTMLElement> = {
 				role: 'option',
 				...(active && { id: floatingId + '-fui-option' }),
 			};
@@ -98,7 +127,7 @@ export function useRole(...args: any[]): any {
 		subSlot(slot, 'cb:item'),
 	);
 
-	return useMemo(
+	return useMemo<ElementProps>(
 		() => (enabled ? { reference, floating, item } : {}),
 		[enabled, reference, floating, item],
 		subSlot(slot, 'm:ret'),

package/src/useTypeahead.ts

@@ -10,11 +10,72 @@ import {
 	useLatestRef,
 	useModernLayoutEffect,
 } from './utils';
+import type { ElementProps, FloatingRootContext, MutableRefObject } from './types';
 
-export function useTypeahead(...args: any[]): any {
+export interface UseTypeaheadProps {
+	/**
+	 * A ref which contains an array of strings whose indices match the HTML
+	 * elements of the list.
+	 * @default empty list
+	 */
+	listRef: MutableRefObject<Array<string | null>>;
+	/**
+	 * The index of the active (focused or highlighted) item in the list.
+	 * @default null
+	 */
+	activeIndex: number | null;
+	/**
+	 * Callback invoked with the matching index if found as the user types.
+	 */
+	onMatch?: (index: number) => void;
+	/**
+	 * Callback invoked with the typing state as the user types.
+	 */
+	onTypingChange?: (isTyping: boolean) => void;
+	/**
+	 * Whether the Hook is enabled, including all internal Effects and event
+	 * handlers.
+	 * @default true
+	 */
+	enabled?: boolean;
+	/**
+	 * A function that returns the matching string from the list.
+	 * @default lowercase-finder
+	 */
+	findMatch?:
+		| null
+		| ((list: Array<string | null>, typedString: string) => string | null | undefined);
+	/**
+	 * The number of milliseconds to wait before resetting the typed string.
+	 * @default 750
+	 */
+	resetMs?: number;
+	/**
+	 * An array of keys to ignore when typing.
+	 * @default []
+	 */
+	ignoreKeys?: Array<string>;
+	/**
+	 * The index of the selected item in the list, if available.
+	 * @default null
+	 */
+	selectedIndex?: number | null;
+}
+
+/**
+ * Provides a matching callback that can be used to focus an item as the user
+ * types, often used in tandem with `useListNavigation()`.
+ * @see https://floating-ui.com/docs/useTypeahead
+ */
+export function useTypeahead(
+	context: FloatingRootContext,
+	props: UseTypeaheadProps,
+	slot?: symbol,
+): ElementProps;
+export function useTypeahead(...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 UseTypeaheadProps) ?? {};
 
 	const open = context.open;
 	const dataRef = context.dataRef;
@@ -31,11 +92,11 @@ export function useTypeahead(...args: any[]): any {
 
 	const timeoutIdRef = useRef(-1, subSlot(slot, 'timeout'));
 	const stringRef = useRef('', subSlot(slot, 'string'));
-	const prevIndexRef = useRef(
+	const prevIndexRef = useRef<number | null>(
 		(selectedIndex != null ? selectedIndex : activeIndex) ?? -1,
 		subSlot(slot, 'prev'),
 	);
-	const matchIndexRef = useRef<any>(null, subSlot(slot, 'match'));
+	const matchIndexRef = useRef<number | null>(null, subSlot(slot, 'match'));
 
 	const onMatch = useEffectEvent(unstableOnMatch, subSlot(slot, 'onmatch'));
 	const onTypingChange = useEffectEvent(unstableOnTypingChange, subSlot(slot, 'ontyping'));
@@ -65,7 +126,7 @@ export function useTypeahead(...args: any[]): any {
 	);
 
 	const setTypingChange = useEffectEvent(
-		(value: any) => {
+		(value: boolean) => {
 			if (value) {
 				if (!dataRef.current.typing) {
 					dataRef.current.typing = value;
@@ -82,8 +143,12 @@ export function useTypeahead(...args: any[]): any {
 	);
 
 	const onKeyDown = useEffectEvent(
-		(event: any) => {
-			function getMatchingIndex(list: any[], orderedList: any[], string: string) {
+		(event: KeyboardEvent) => {
+			function getMatchingIndex(
+				list: Array<string | null>,
+				orderedList: Array<string | null>,
+				string: string,
+			) {
 				const str = findMatchRef.current
 					? findMatchRef.current(orderedList, string)
 					: orderedList.find(
@@ -150,7 +215,7 @@ export function useTypeahead(...args: any[]): any {
 	const floating = useMemo(
 		() => ({
 			onKeyDown,
-			onKeyUp(event: any) {
+			onKeyUp(event: KeyboardEvent) {
 				if (event.key === ' ') {
 					setTypingChange(false);
 				}
@@ -160,7 +225,7 @@ export function useTypeahead(...args: any[]): any {
 		subSlot(slot, 'm:flo'),
 	);
 
-	return useMemo(
+	return useMemo<ElementProps>(
 		() => (enabled ? { reference, floating } : {}),
 		[enabled, reference, floating],
 		subSlot(slot, 'm:ret'),