@necto-react/hooks 2.12.6 → 2.13.0

package/dist/index.d.cts

@@ -1,6 +1,8 @@
-import { ForwardedRef, Context, HTMLAttributes, RefObject, FocusEvent, ReactNode, CSSProperties } from 'react';
-import { DisabledFlags, FocusEvents, DOMAttributes, FocusableDOMProps, HoverEvent, KeyboardEvents, RenderProps } from '@necto-react/types';
-import { FocusableElement, PressEvent } from '@necto/types';
+import { ForwardedRef, Context, RefObject, FocusEvent, ReactNode, CSSProperties, AriaAttributes, useLayoutEffect, PointerEvent, MouseEvent as MouseEvent$1 } from 'react';
+import { FocusableElement, PressEvent, KeyboardDelegate, Key } from '@necto/types';
+export { KeyboardDelegate } from '@necto/types';
+import { FocusEvents, DOMAttributes, FocusableDOMProps, HoverEvent, KeyboardEvents, RenderProps, SelectionManager, FocusStrategy } from '@necto-react/types';
+export { FocusStrategy, SelectionManager, SelectionMode } from '@necto-react/types';
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -11,9 +13,9 @@ import { FocusableElement, PressEvent } from '@necto/types';
  */
 
 /**
- * Props for the useContextProps hook.
+ * Options for the useContextProps hook.
  */
-interface UseContextPropsProps<T, E extends Element> {
+interface UseContextPropsOptions<T, E extends Element> {
     /**
      * Component props, must include optional slot property and optional ref.
      */
@@ -61,87 +63,10 @@ type UseContextPropsReturn<T, E extends Element> = [
  *
  * @template T The props type.
  * @template E The element type.
- * @param {UseContextPropsProps<T, E>} params - Component props, ref, and context.
+ * @param {UseContextPropsOptions<T, E>} options - Component props, ref, and context.
  * @returns {UseContextPropsReturn<T, E>} A tuple of merged props and merged ref.
  */
-declare function useContextProps<T, E extends Element>({ props, ref, context }: UseContextPropsProps<T, E>): UseContextPropsReturn<T, E>;
-
-/**
- * Copyright (c) Corinvo, LLC. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-
-/**
- * Props for the useDisabled hook.
- */
-interface UseDisabledProps {
-    /** The key of the disabled flag to check. Defaults to 'general'. */
-    type?: keyof DisabledFlags;
-    /** The fallback value if the flag is not set. Defaults to false. */
-    defaultFallback?: boolean;
-}
-/**
- * Return type for the useDisabled hook.
- */
-type UseDisabledPropsReturn = boolean;
-
-/**
- * Copyright (c) Corinvo, LLC. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-
-/**
- * React hook to determine if a specific feature or component type is disabled.
- *
- * @param {keyof DisabledFlags} type - The key of the disabled flag to check. Defaults to 'general'.
- * @param {boolean} defaultFallback - The fallback value if the flag is not set. Defaults to false.
- * @returns {boolean} True if the specified type is disabled, otherwise the fallback value.
- */
-declare function useDisabled(props?: UseDisabledProps): UseDisabledPropsReturn;
-
-/**
- * Copyright (c) Corinvo, LLC. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-
-/**
- * Props for the useDisabledProps hook.
- */
-interface UseDisabledPropsProps {
-    /** The key of the disabled flag to check. Defaults to 'general'. */
-    type?: keyof DisabledFlags;
-    /** Additional props to merge with the disabled attributes. */
-    extraProps?: HTMLAttributes<HTMLElement>;
-}
-/**
- * Return type for the useDisabledProps hook.
- */
-type UseDisabledPropsPropsReturn = HTMLAttributes<HTMLElement>;
-
-/**
- * Copyright (c) Corinvo, LLC. and affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- *
- */
-
-/**
- * Returns HTML props with appropriate disabled attributes based on the disabled state.
- *
- * @param {UseDisabledPropsOptions} options - Options for the hook.
- * @returns {HTMLAttributes<HTMLElement>} The merged props including disabled and aria-disabled if applicable.
- */
-declare function useDisabledProps(props?: UseDisabledPropsProps): UseDisabledPropsPropsReturn;
+declare function useContextProps<T, E extends Element>({ props, ref, context }: UseContextPropsOptions<T, E>): UseContextPropsReturn<T, E>;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -155,9 +80,9 @@ declare function useDisabledProps(props?: UseDisabledPropsProps): UseDisabledPro
  */
 type PartialVisibility = boolean | 'top' | 'right' | 'bottom' | 'left';
 /**
- * Props for the useElementVisibility hook.
+ * Options for the useElementVisibility hook.
  */
-interface UseElementVisibilityProps {
+interface UseElementVisibilityOptions {
     /** Whether partial visibility is allowed, or which edge to check. */
     partialVisibility?: PartialVisibility;
     /** The threshold(s) at which to trigger the observer callback. */
@@ -209,10 +134,10 @@ type UseElementVisibilityReturn<T extends Element = Element> = [
  * React hook that observes the visibility of a DOM element using the Intersection Observer API.
  *
  * @template T The type of the element being observed.
- * @param {UseElementVisibilityProps} [props] - Options to control visibility observation and callbacks.
+ * @param {UseElementVisibilityOptions} [options] - Options to control visibility observation and callbacks.
  * @returns {UseElementVisibilityReturn<T>} A tuple containing the ref to the element, the visibility state, and intersection details.
  */
-declare function useElementVisibility<T extends Element = Element>(props?: UseElementVisibilityProps): UseElementVisibilityReturn<T>;
+declare function useElementVisibility<T extends Element = Element>(options?: UseElementVisibilityOptions): UseElementVisibilityReturn<T>;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -223,9 +148,9 @@ declare function useElementVisibility<T extends Element = Element>(props?: UseEl
  */
 
 /**
- * Props for the useFocus hook.
+ * Options for the useFocus hook.
  */
-interface UseFocusProps<T = FocusableElement> extends FocusEvents<T> {
+interface UseFocusOptions<T = FocusableElement> extends FocusEvents<T> {
     /** Whether focus events are disabled. */
     isDisabled?: boolean;
 }
@@ -256,10 +181,10 @@ interface UseFocusReturn<T = FocusableElement> {
  * React hook that manages focus and blur event handling for a focusable element.
  *
  * @template T The type of the focusable element.
- * @param {UseFocusProps<T>} [props] - Options and event handlers for focus management.
+ * @param {UseFocusOptions<T>} [options] - Options and event handlers for focus management.
  * @returns {UseFocusReturn<T>} An object containing props to spread on the target element for focus management.
  */
-declare function useFocus<T extends FocusableElement = FocusableElement>(props?: UseFocusProps<T>): UseFocusReturn<T>;
+declare function useFocus<T extends FocusableElement = FocusableElement>(options?: UseFocusOptions<T>): UseFocusReturn<T>;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -269,7 +194,10 @@ declare function useFocus<T extends FocusableElement = FocusableElement>(props?:
  *
  */
 
-interface UseFocusableProps extends FocusableDOMProps, FocusEvents {
+/**
+ * Options for the useFocusable hook.
+ */
+interface UseFocusableOptions extends FocusableDOMProps, FocusEvents {
     isDisabled?: boolean;
     autoFocus?: boolean;
 }
@@ -296,11 +224,11 @@ type UseFocusableReturn = Readonly<{
  * React hook that provides focus management and keyboard accessibility for a focusable element.
  * Handles autofocus, disabled state, tab order, and merges focus and keyboard props.
  *
- * @param {UseFocusableProps} props - Props controlling focus behavior and accessibility.
+ * @param {UseFocusableOptions} options - Options controlling focus behavior and accessibility.
  * @param {RefObject<FocusableElement | null>} domRef - Ref to the DOM element to manage focus for.
  * @returns {UseFocusableReturn} Object containing merged props for focusable behavior.
  */
-declare function useFocusable(props: UseFocusableProps, domRef: RefObject<FocusableElement | null>): UseFocusableReturn;
+declare function useFocusable(options: UseFocusableOptions, domRef: RefObject<FocusableElement | null>): UseFocusableReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -311,9 +239,9 @@ declare function useFocusable(props: UseFocusableProps, domRef: RefObject<Focusa
  */
 
 /**
- * Props for the useFocusRing hook.
+ * Options for the useFocusRing hook.
  */
-interface UseFocusRingProps {
+interface UseFocusRingOptions {
     /** Whether to track focus visibility within a subtree instead of just the element. */
     within?: boolean;
     /** Whether the target element is a text input. */
@@ -351,10 +279,10 @@ interface UseFocusRingReturn {
 /**
  * React hook that manages focus state and focus ring visibility for an element.
  *
- * @param {UseFocusRingProps} [props] - Options to control focus ring behavior.
+ * @param {UseFocusRingOptions} [options] - Options to control focus ring behavior.
  * @returns {UseFocusRingReturn} An object containing focus state, focus visibility, and props to spread on the target element.
  */
-declare function useFocusRing(props?: UseFocusRingProps): UseFocusRingReturn;
+declare function useFocusRing(options?: UseFocusRingOptions): UseFocusRingReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -364,9 +292,9 @@ declare function useFocusRing(props?: UseFocusRingProps): UseFocusRingReturn;
  *
  */
 /**
- * Props for the useFocusVisible hook.
+ * Options for the useFocusVisible hook.
  */
-interface UseFocusVisibleProps {
+interface UseFocusVisibleOptions {
     /** Whether the target element is a text input. */
     isTextInput?: boolean;
     /** Whether the element should automatically receive focus when mounted. */
@@ -398,10 +326,10 @@ interface UseFocusVisibleReturn {
 /**
  * React hook that provides focus visibility tracking.
  *
- * @param {UseFocusVisibleProps} [props] - Options for focus visibility behavior.
+ * @param {UseFocusVisibleOptions} [options] - Options for focus visibility behavior.
  * @returns {UseFocusVisibleReturn} An object containing the focus visibility state.
  */
-declare function useFocusVisible(props?: UseFocusVisibleProps): UseFocusVisibleReturn;
+declare function useFocusVisible(options?: UseFocusVisibleOptions): UseFocusVisibleReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -419,9 +347,9 @@ declare function useFocusVisible(props?: UseFocusVisibleProps): UseFocusVisibleR
  */
 type Modality = 'keyboard' | 'pointer' | 'virtual';
 /**
- * Props for the useFocusVisibleListener hook.
+ * Options for the useFocusVisibleListener hook.
  */
-interface UseFocusVisibleListenerProps {
+interface UseFocusVisibleListenerOptions {
     /** Function called when focus visibility changes. */
     fn: (isFocusVisible: boolean) => void;
     /** Dependency array that determines when to rebind the listener. */
@@ -450,10 +378,10 @@ declare function getInteractionModality(): Modality | null;
 /**
  * React hook that listens for focus visibility changes based on interaction modality.
  *
- * @param {UseFocusVisibleListenerProps} props - The props for the focus visible listener.
+ * @param {UseFocusVisibleListenerOptions} options - The options for the focus visible listener.
  * @returns {void}
  */
-declare function useFocusVisibleListener(props: UseFocusVisibleListenerProps): void;
+declare function useFocusVisibleListener(options: UseFocusVisibleListenerOptions): void;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -464,9 +392,9 @@ declare function useFocusVisibleListener(props: UseFocusVisibleListenerProps): v
  */
 
 /**
- * Props for the useFocusWithin hook.
+ * Options for the useFocusWithin hook.
  */
-interface UseFocusWithinProps {
+interface UseFocusWithinOptions {
     /** Whether the focus events should be disabled. */
     isDisabled?: boolean;
     /** Handler that is called when focus enters the element or its descendants. */
@@ -499,7 +427,7 @@ interface FocusWithinReturn {
  * Modifications have been made to adapt the code for use in this project.
  */
 
-declare function useFocusWithin(props: UseFocusWithinProps): FocusWithinReturn;
+declare function useFocusWithin(options: UseFocusWithinOptions): FocusWithinReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -618,9 +546,9 @@ declare function useHover(props?: UseHoverProps): UseHoverReturn;
  *
  */
 /**
- * Props for the useId hook.
+ * Options for the useId hook.
  */
-interface UseIdProps {
+interface UseIdOptions {
     /** Optional custom prefix for the generated ID. */
     prefix?: string;
     /** Optional default ID to use instead of generating one. */
@@ -630,10 +558,10 @@ interface UseIdProps {
 /**
  * Generates a unique, stable ID for React components, optionally with a custom prefix.
  *
- * @param {UseIdProps} [props] - Optional props object. You can provide a custom prefix and/or a defaultId.
- * @returns {UseIdReturns} The generated or provided unique ID.
+ * @param {UseIdOptions} [options] - Optional options object. You can provide a custom prefix and/or a defaultId.
+ * @returns {string} The generated or provided unique ID.
  */
-declare function useId(props?: UseIdProps): string;
+declare function useId(options?: UseIdOptions): string;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -644,9 +572,9 @@ declare function useId(props?: UseIdProps): string;
  */
 
 /**
- * Props for the useKeyboard hook.
+ * Options for the useKeyboard hook.
  */
-interface UseKeyboardProps extends KeyboardEvents {
+interface UseKeyboardOptions extends KeyboardEvents {
     /**
      * Whether the keyboard interaction is disabled.
      * Defaults to false.
@@ -674,10 +602,10 @@ interface UseKeyboardReturn {
 /**
  * React hook that provides keyboard event handlers based on the disabled state.
  *
- * @param {UseKeyboardProps} props - Props controlling keyboard interaction.
+ * @param {UseKeyboardOptions} options - Options controlling keyboard interaction.
  * @returns {UseKeyboardReturn} Object containing keyboard event handler props.
  */
-declare function useKeyboard(props: UseKeyboardProps): UseKeyboardReturn;
+declare function useKeyboard(options: UseKeyboardOptions): UseKeyboardReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -692,9 +620,9 @@ declare function useKeyboard(props: UseKeyboardProps): UseKeyboardReturn;
  */
 type MountedAccessType = 'function' | 'ref' | 'boolean';
 /**
- * Props for the useMounted hook.
+ * Options for the useMounted hook.
  */
-interface UseMountedProps {
+interface UseMountedOptions {
     /** The type of access to the mounted state. */
     type?: MountedAccessType;
 }
@@ -719,10 +647,10 @@ type UseMountedReturn<T extends MountedAccessType> = T extends 'ref' ? RefObject
  * React hook that tracks whether a component is mounted.
  *
  * @template T The type of access to the mounted state (function, ref, or boolean).
- * @param {UseMountedProps & { type: T }} [props] - Options to configure the hook behavior.
+ * @param {UseMountedOptions & { type: T }} [options] - Options to configure the hook behavior.
  * @returns {UseMountedReturn<T>} The mounted state in the requested format.
  */
-declare function useMounted<T extends MountedAccessType = 'function'>(props?: UseMountedProps & {
+declare function useMounted<T extends MountedAccessType = 'function'>(options?: UseMountedOptions & {
     type: T;
 }): UseMountedReturn<T>;
 
@@ -797,9 +725,9 @@ declare function usePress(props?: UsePressProps): UsePressReturn;
  */
 
 /**
- * Props for the useRendererHook
+ * Options for the useRenderer hook.
  */
-interface UseRendererProps<T> extends RenderProps<T> {
+interface UseRendererOptions<T> extends RenderProps<T> {
     id?: string;
     values: T;
     defaultChildren?: ReactNode;
@@ -824,7 +752,13 @@ interface UseRendererReturn {
  *
  */
 
-declare function useRenderer<T>(props: UseRendererProps<T>): UseRendererReturn;
+/**
+ * React hook that handles rendering logic for components with render props.
+ *
+ * @param {UseRendererOptions} options - Options for the hook.
+ * @returns {UseRendererReturn} The resolved rendering properties.
+ */
+declare function useRenderer<T>(options: UseRendererOptions<T>): UseRendererReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -888,22 +822,19 @@ declare function useSlottedContext<T>(props: UseSlottedContextProps<T>): UseSlot
  */
 
 /**
- * Props for synchronizing a context ref with a local ref.
- *
- * @template T The type of the element or value referenced.
+ * Options for the useSyntheticBlurEvent hook.
  */
-interface UseSyncContextRefProps<T> {
+interface UseSyntheticBlurEventOptions<T extends Element = Element> {
     /**
-     * Optional context object containing a ref to synchronize.
-     */
-    context?: {
-        ref?: RefObject<T | null>;
-    };
-    /**
-     * Optional local ref to synchronize with the context ref.
+     * Handler called when the blur event is triggered on the target element.
+     * Receives a React FocusEvent for the target element.
      */
-    ref?: RefObject<T | null>;
+    onBlur: (event: FocusEvent<T>) => void;
 }
+/**
+ * Return type for the useSyntheticBlurEvent hook.
+ */
+type UseSyntheticBlurEventReturn<T> = (event: FocusEvent<T>) => void;
 
 /**
  * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
@@ -920,7 +851,66 @@ interface UseSyncContextRefProps<T> {
  * Modifications have been made to adapt the code for use in this project.
  */
 
-declare function useSyncContextRef<T>(props?: UseSyncContextRefProps<T>): void;
+/**
+ * React hook to handle synthetic blur events, particularly for disabled elements.
+ *
+ * @param {UseSyntheticBlurEventOptions} options - Options for the hook.
+ * @returns A callback to attach to the element's blur event.
+ */
+declare function useSyntheticBlurEvent<T extends Element = Element>(options: UseSyntheticBlurEventOptions<T>): UseSyntheticBlurEventReturn<T>;
+
+/**
+ * Returns a stable event callback that always invokes the latest version of the provided function.
+ *
+ * @param {T} fn - The event handler function to stabilize.
+ * @returns {T} A memoized callback that always calls the latest version of `fn`.
+ */
+declare function useEffectEvent<T extends (...args: any[]) => any>(fn: T): T;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * React hook that determines if a browser feature is supported.
+ *
+ * @param {() => unknown} fn - Function that tests for feature support.
+ * @returns {boolean} Whether the feature is supported in the current environment.
+ */
+declare function useSupported(fn: () => unknown): boolean;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * Options for the useScrollLock hook.
+ */
+interface UseScrollLockOptions {
+    /** Whether to automatically lock scroll on mount. */
+    autoLock?: boolean;
+    /** The target element to lock scrolling on. Can be an HTMLElement or a CSS selector string. Defaults to document.body. */
+    target?: HTMLElement | string;
+    /** Whether to add padding to prevent layout shift when scrollbar is hidden. */
+    widthReflow?: boolean;
+}
+/**
+ * Return type for the useScrollLock hook.
+ */
+interface UseScrollLockReturn {
+    /** Whether scroll is currently locked. */
+    isLocked: boolean;
+    /** Function to lock scrolling. */
+    lock: () => void;
+    /** Function to unlock scrolling. */
+    unlock: () => void;
+}
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -931,19 +921,182 @@ declare function useSyncContextRef<T>(props?: UseSyncContextRefProps<T>): void;
  */
 
 /**
- * Props for the useSyntheticBlurEvent hook.
+ * React hook that locks scrolling on a target element or the entire page.
+ *
+ * @param {UseScrollLockOptions} [options] - Options to configure scroll lock behavior.
+ * @returns {UseScrollLockReturn} An object with isLocked state and lock/unlock functions.
+ */
+declare function useScrollLock(options?: UseScrollLockOptions): UseScrollLockReturn;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * Options for the useAriaProps hook.
+ */
+interface UseAriaPropsOptions {
+    /** Whether the element is invalid. */
+    isInvalid?: boolean;
+    /** Whether the element is disabled. */
+    isDisabled?: boolean;
+    /** Whether the element is read-only. */
+    isReadOnly?: boolean;
+    /** Whether the element is required. */
+    isRequired?: boolean;
+    /** Whether the element is busy. */
+    isBusy?: boolean;
+    /** Whether the element is pressed. */
+    isPressed?: boolean | 'mixed';
+    /** Whether the element is expanded. */
+    isExpanded?: boolean;
+    /** Whether the element is selected. */
+    isSelected?: boolean;
+    /** Whether the element is checked. */
+    isChecked?: boolean | 'mixed';
+    /** Whether the element is hidden. */
+    isHidden?: boolean;
+    /** Whether the element has a popup. */
+    hasPopup?: boolean | 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog';
+    /** The current value (for range widgets). */
+    valueCurrent?: number;
+    /** The minimum value (for range widgets). */
+    valueMin?: number;
+    /** The maximum value (for range widgets). */
+    valueMax?: number;
+    /** The current value as text (for range widgets). */
+    valueText?: string;
+    /** A label for the element. */
+    label?: string;
+    /** ID of the element that labels this element. */
+    labelledBy?: string;
+    /** ID of the element that describes this element. */
+    describedBy?: string;
+    /** ID of the element that this element controls. */
+    controls?: string;
+    /** ID of the element that owns this element. */
+    owns?: string;
+}
+/**
+ * Return type for the useAriaProps hook.
  */
-interface UseSyntheticBlurEventProps<T extends Element = Element> {
+type UseAriaPropsReturn = AriaAttributes;
+
+/**
+ * Returns ARIA attributes based on the provided state flags.
+ * Automatically filters out undefined values to avoid adding empty ARIA attributes.
+ *
+ * @param {UseAriaPropsOptions} options - State flags to convert to ARIA attributes.
+ * @returns {UseAriaPropsReturn} The ARIA attributes object with only defined values.
+ */
+declare function useAriaProps(options?: UseAriaPropsOptions): UseAriaPropsReturn;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+/**
+ * Options for the useStyleInjection hook.
+ */
+interface UseStyleInjectionOptions {
+    id?: string;
+    css: string | string[];
+    window?: Window | null;
+    insertionPoint?: HTMLElement | null;
+    enabled?: boolean;
+}
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * React hook that injects CSS styles into the document.
+ *
+ * @param {UseStyleInjectionOptions} options - Options for the hook.
+ */
+declare function useStyleInjection({ id, css, insertionPoint, enabled, window: targetWindow }: UseStyleInjectionOptions): void;
+
+declare function useLatestRef<T>(value: T): React.RefObject<T>;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+declare const useIsomorphicInsertionEffect: typeof useLayoutEffect;
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+/**
+ * Event passed to long press callbacks.
+ */
+interface LongPressEvent {
+    /** The type of event. */
+    type: 'longpressstart' | 'longpressend' | 'longpress';
+    /** The pointer type that triggered the event. */
+    pointerType: PressEvent['pointerType'];
+    /** The target element. */
+    target: EventTarget;
+}
+/**
+ * Options for the useLongPress hook.
+ */
+interface UseLongPressOptions {
+    /** Whether long press events are disabled. */
+    isDisabled?: boolean;
+    /** Ref to the target element. */
+    ref?: RefObject<HTMLElement | null>;
+    /** Handler called when a long press interaction starts. */
+    onLongPressStart?: (e: LongPressEvent) => void;
+    /** Handler called when a long press interaction ends. */
+    onLongPressEnd?: (e: LongPressEvent) => void;
+    /** Handler called when the long press threshold is reached. */
+    onLongPress?: (e: LongPressEvent) => void;
     /**
-     * Handler called when the blur event is triggered on the target element.
-     * Receives a React FocusEvent for the target element.
+     * The duration in milliseconds before a press is considered a long press.
+     * @default 500
      */
-    onBlur: (event: FocusEvent<T>) => void;
+    threshold?: number;
+    /**
+     * A description for assistive technology users indicating that a long press
+     * action is available, e.g. "Long press to open menu".
+     */
+    accessibilityDescription?: string;
 }
 /**
- * Return type for the useSyntheticBlurEvent hook.
+ * Return value from the useLongPress hook.
  */
-type UseSyntheticBlurEventReturn<T> = (event: FocusEvent<T>) => void;
+interface UseLongPressReturn {
+    /** Props to spread on the target element for long press behavior. */
+    longPressProps: {
+        onPointerDown?: (e: PointerEvent) => void;
+        onPointerUp?: (e: PointerEvent) => void;
+        onPointerCancel?: (e: PointerEvent) => void;
+        onContextMenu?: (e: MouseEvent$1) => void;
+        'aria-description'?: string;
+    };
+}
 
 /**
  * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
@@ -961,20 +1114,72 @@ type UseSyntheticBlurEventReturn<T> = (event: FocusEvent<T>) => void;
  */
 
 /**
- * React hook to handle synthetic blur events, particularly for disabled elements.
+ * Handles long press interactions for touch and pointer devices.
+ * A long press is triggered when the user holds down a pointer for a specified duration.
+ */
+declare function useLongPress(options?: UseLongPressOptions): UseLongPressReturn;
+
+/**
+ * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
+ * licensed under the Apache License, Version 2.0.
+ * Copyright (c) Adobe. All rights reserved.
+ * See: https://github.com/adobe/react-spectrum
  *
- * @param onBlur - Callback to handle the blur event.
- * @returns A callback to attach to the element's blur event.
+ * Modifications copyright (c) Corinvo, LLC. and affiliates. All rights reserved.
+ *
+ * This file contains code licensed under:
+ * - The MIT License (see LICENSE in the root directory) for Corinvo modifications.
+ * - The Apache License, Version 2.0 for portions from Adobe.
+ *
+ * Modifications have been made to adapt the code for use in this project.
  */
-declare function useSyntheticBlurEvent<T extends Element = Element>(props: UseSyntheticBlurEventProps<T>): UseSyntheticBlurEventReturn<T>;
 
 /**
- * Returns a stable event callback that always invokes the latest version of the provided function.
+ * Options for the useAnimation hook.
+ */
+interface UseAnimationOptions {
+    /** A ref to the element being animated. */
+    ref: RefObject<HTMLElement | null>;
+    /** Whether the element is currently open/visible. Controls enter and exit animations. */
+    isOpen: boolean;
+    /** Whether the element is ready for the enter animation. @default true */
+    isReady?: boolean;
+}
+/**
+ * Return type for the useAnimation hook.
+ */
+interface UseAnimationReturn {
+    /** Whether the element is currently in the entering animation phase. */
+    isEntering: boolean;
+    /** Whether the element is currently in the exiting animation phase. */
+    isExiting: boolean;
+    /** Whether the element should be rendered (open or still exiting). */
+    isRendered: boolean;
+}
+
+/**
+ * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
+ * licensed under the Apache License, Version 2.0.
+ * Copyright (c) Adobe. All rights reserved.
+ * See: https://github.com/adobe/react-spectrum
  *
- * @param {T} fn - The event handler function to stabilize.
- * @returns {T} A memoized callback that always calls the latest version of `fn`.
+ * Modifications copyright (c) Corinvo, LLC. and affiliates. All rights reserved.
+ *
+ * This file contains code licensed under:
+ * - The MIT License (see LICENSE in the root directory) for Corinvo modifications.
+ * - The Apache License, Version 2.0 for portions from Adobe.
+ *
+ * Modifications have been made to adapt the code for use in this project.
  */
-declare function useEffectEvent<T extends (...args: any[]) => any>(fn: T): T;
+
+/**
+ * Manages enter and exit CSS animations/transitions on a ref element.
+ *
+ * - When `isOpen` becomes `true`, the element enters an entering phase until all animations finish.
+ * - When `isOpen` becomes `false`, the element enters an exiting phase and stays mounted until all animations complete.
+ * - `isRendered` indicates whether the element should remain in the DOM (open or still exiting).
+ */
+declare function useAnimation(options: UseAnimationOptions): UseAnimationReturn;
 
 /**
  * Copyright (c) Corinvo, LLC. and affiliates.
@@ -983,12 +1188,239 @@ declare function useEffectEvent<T extends (...args: any[]) => any>(fn: T): T;
  * LICENSE file in the root directory of this source tree.
  *
  */
+
+/** Direction for text/layout. */
+type Direction = 'ltr' | 'rtl';
+/** Orientation of the collection. */
+type Orientation = 'horizontal' | 'vertical' | 'both';
+/** Behavior when Escape key is pressed. */
+type EscapeBehavior = 'clearSelection' | 'none';
+/** Behavior for link items in the collection. */
+type LinkBehavior = 'action' | 'selection' | 'override';
 /**
- * React hook that determines if a browser feature is supported.
+ * Options for useCollectionNavigation hook.
+ */
+interface UseCollectionNavigationOptions {
+    /**
+     * Manager for reading and updating selection state.
+     */
+    selectionManager: SelectionManager;
+    /**
+     * Delegate for keyboard navigation behavior.
+     */
+    keyboardDelegate: KeyboardDelegate;
+    /**
+     * Ref to the collection container element.
+     */
+    ref: RefObject<HTMLElement | null>;
+    /**
+     * Whether to auto-focus on mount.
+     * @default false
+     */
+    autoFocus?: boolean | FocusStrategy;
+    /**
+     * Whether focus should wrap at ends.
+     * @default false
+     */
+    shouldFocusWrap?: boolean;
+    /**
+     * Whether empty selection is disallowed.
+     * @default false
+     */
+    disallowEmptySelection?: boolean;
+    /**
+     * Whether Ctrl+A select all is disallowed.
+     * @default false
+     */
+    disallowSelectAll?: boolean;
+    /**
+     * Behavior when Escape is pressed.
+     * @default 'clearSelection'
+     */
+    escapeBehavior?: EscapeBehavior;
+    /**
+     * Whether to select items on focus.
+     * @default false
+     */
+    selectOnFocus?: boolean;
+    /**
+     * Whether type-ahead is disabled.
+     * @default false
+     */
+    disallowTypeAhead?: boolean;
+    /**
+     * Whether to use virtual focus (aria-activedescendant).
+     * @default false
+     */
+    shouldUseVirtualFocus?: boolean;
+    /**
+     * Whether Tab key navigation is allowed.
+     * @default false
+     */
+    allowsTabNavigation?: boolean;
+    /**
+     * Whether the collection is virtualized.
+     * @default false
+     */
+    isVirtualized?: boolean;
+    /**
+     * Ref to the scrollable container (defaults to ref).
+     */
+    scrollRef?: RefObject<HTMLElement | null>;
+    /**
+     * Text direction for RTL support.
+     * @default 'ltr'
+     */
+    direction?: Direction;
+    /**
+     * Orientation of the collection.
+     * @default 'vertical'
+     */
+    orientation?: Orientation;
+    /**
+     * Disabled keys in the collection.
+     */
+    disabledKeys?: Set<Key>;
+    /**
+     * Called when navigation occurs.
+     */
+    onNavigate?: (key: Key | null) => void;
+    /**
+     * Called when an item should be focused.
+     */
+    onFocusItem?: (key: Key) => void;
+}
+/**
+ * Return value from useCollectionNavigation hook.
+ */
+interface UseCollectionNavigationReturn {
+    /** Props to spread on the collection element. */
+    collectionProps: DOMAttributes;
+}
+
+/**
+ * Copyright (c) Corinvo, LLC. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
  *
- * @param {() => unknown} fn - Function that tests for feature support.
- * @returns {boolean} Whether the feature is supported in the current environment.
  */
-declare function useSupported(fn: () => unknown): boolean;
 
-export { type FocusWithinReturn, type UseContextPropsProps, type UseContextPropsReturn, type UseDisabledProps, type UseDisabledPropsProps, type UseDisabledPropsPropsReturn, type UseDisabledPropsReturn, type UseElementVisibilityProps, type UseElementVisibilityReturn, type UseFocusProps, type UseFocusReturn, type UseFocusRingProps, type UseFocusRingReturn, type UseFocusVisibleListenerProps, type UseFocusVisibleProps, type UseFocusVisibleReturn, type UseFocusWithinProps, type UseFocusableProps, type UseFocusableReturn, type UseGlobalListenersReturn, type UseHoverProps, type UseHoverReturn, type UseIdProps, type UseMountedProps, type UseMountedReturn, type UsePressProps, type UsePressReturn, type UseRendererProps, type UseRendererReturn, type UseSlottedContextProps, type UseSlottedContextReturn, type UseSyncContextRefProps, type UseSyntheticBlurEventProps, type UseSyntheticBlurEventReturn, getInteractionModality, useContextProps, useDisabled, useDisabledProps, useEffectEvent, useElementVisibility, useFocus, useFocusRing, useFocusVisible, useFocusVisibleListener, useFocusWithin, useFocusable, useGlobalListeners, useHover, useId, useKeyboard, useMounted, usePress, useRenderer, useSlottedContext, useSupported, useSyncContextRef, useSyntheticBlurEvent };
+/**
+ * Handles keyboard navigation and selection for collections.
+ * Supports lists, grids, tabs, menus, and other selectable collections.
+ */
+declare function useCollectionNavigation(options: UseCollectionNavigationOptions): UseCollectionNavigationReturn;
+
+/**
+ * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
+ * licensed under the Apache License, Version 2.0.
+ * Copyright (c) Adobe. All rights reserved.
+ * See: https://github.com/adobe/react-spectrum
+ *
+ * Modifications copyright (c) Corinvo, LLC. and affiliates. All rights reserved.
+ *
+ * This file contains code licensed under:
+ * - The MIT License (see LICENSE in the root directory) for Corinvo modifications.
+ * - The Apache License, Version 2.0 for portions from Adobe.
+ *
+ * Modifications have been made to adapt the code for use in this project.
+ */
+/** A validation error message string, or an array of messages. */
+type ValidationError = string | string[];
+/** A map of field names to their validation errors, used for server-side error propagation. */
+type ValidationErrors = Record<string, ValidationError>;
+/** A function that validates a value and returns error messages, or `true`/`null` for valid. */
+type ValidationFunction<T> = (value: T) => ValidationError | true | null | undefined;
+/** The result of validating a form field value. */
+interface ValidationResult {
+    /** Whether the value is invalid. */
+    isInvalid: boolean;
+    /** The validation error messages. */
+    validationErrors: string[];
+    /** The native validity state details. */
+    validationDetails: ValidityState;
+}
+/** Component-facing validation props for form fields. */
+interface Validation<T> {
+    /** Whether the value is invalid. */
+    isInvalid?: boolean;
+    /**
+     * @deprecated Use `isInvalid` instead.
+     * Whether the value is valid or invalid.
+     */
+    validationState?: 'valid' | 'invalid';
+    /**
+     * Controls when validation errors are displayed.
+     * - `'aria'`: errors are displayed in realtime as the user edits.
+     * - `'native'`: errors are displayed on form submit or explicit commit.
+     * @default 'aria'
+     */
+    validationBehavior?: 'aria' | 'native';
+    /** A custom validation function for the field value. */
+    validate?: ValidationFunction<T>;
+}
+/** Options for the `useFormState` hook. */
+interface UseFormStateOptions<T> extends Validation<T> {
+    /** The current value of the form field. */
+    value: T | null;
+    /** The name of the form field, used to look up server errors from context. */
+    name?: string | string[];
+    /** Built-in browser validation result, passed from the native element. */
+    builtinValidation?: ValidationResult;
+}
+/** Return type for the `useFormState` hook. */
+interface UseFormStateReturn {
+    /** Realtime validation results, updated as the user edits the value. */
+    realtimeValidation: ValidationResult;
+    /** Currently displayed validation results, updated when the user commits their changes. */
+    displayValidation: ValidationResult;
+    /** Updates the current validation result. Not displayed to the user until `commitValidation` is called. */
+    updateValidation(result: ValidationResult): void;
+    /** Resets the displayed validation state to valid when the user resets the form. */
+    resetValidation(): void;
+    /** Commits the realtime validation so it is displayed to the user. */
+    commitValidation(): void;
+}
+
+/**
+ * Portions of this file are based on code from the React Aria Spectrum library by Adobe,
+ * licensed under the Apache License, Version 2.0.
+ * Copyright (c) Adobe. All rights reserved.
+ * See: https://github.com/adobe/react-spectrum
+ *
+ * Modifications copyright (c) Corinvo, LLC. and affiliates. All rights reserved.
+ *
+ * This file contains code licensed under:
+ * - The MIT License (see LICENSE in the root directory) for Corinvo modifications.
+ * - The Apache License, Version 2.0 for portions from Adobe.
+ *
+ * Modifications have been made to adapt the code for use in this project.
+ */
+
+/** An all-valid `ValidityState` where every constraint passes. */
+declare const VALID_VALIDITY_STATE: ValidityState;
+/** The default validation result representing a valid state. */
+declare const DEFAULT_VALIDATION_RESULT: ValidationResult;
+/** Context for propagating server-side validation errors to form fields. */
+declare const FormValidationContext: Context<ValidationErrors>;
+/**
+ * Private prop key used by parent form components (e.g. a future `useForm`)
+ * to pass pre-computed validation state to child fields, avoiding redundant computation.
+ */
+declare const privateValidationStateProp: string;
+/**
+ * Manages form field validation state, combining custom validation,
+ * built-in browser validation, server errors, and controlled invalid state.
+ *
+ * Returns realtime and display validation results along with methods
+ * to update, reset, and commit validation.
+ */
+declare function useFormState<T>(props: UseFormStateOptions<T>): UseFormStateReturn;
+/**
+ * Merges multiple validation results into one, combining error messages
+ * and validity details. Useful for group components (e.g. checkbox groups).
+ */
+declare function mergeValidation(...results: ValidationResult[]): ValidationResult;
+
+export { DEFAULT_VALIDATION_RESULT, type Direction, type EscapeBehavior, type FocusWithinReturn, FormValidationContext, type LinkBehavior, type LongPressEvent, type Orientation, type UseAnimationOptions, type UseAnimationReturn, type UseAriaPropsOptions, type UseAriaPropsReturn, type UseCollectionNavigationOptions, type UseCollectionNavigationReturn, type UseContextPropsOptions, type UseContextPropsReturn, type UseElementVisibilityOptions, type UseElementVisibilityReturn, type UseFocusOptions, type UseFocusReturn, type UseFocusRingOptions, type UseFocusRingReturn, type UseFocusVisibleListenerOptions, type UseFocusVisibleOptions, type UseFocusVisibleReturn, type UseFocusWithinOptions, type UseFocusableOptions, type UseFocusableReturn, type UseFormStateOptions, type UseFormStateReturn, type UseGlobalListenersReturn, type UseHoverProps, type UseHoverReturn, type UseIdOptions, type UseLongPressOptions, type UseLongPressReturn, type UseMountedOptions, type UseMountedReturn, type UsePressProps, type UsePressReturn, type UseRendererOptions, type UseRendererReturn, type UseScrollLockOptions, type UseScrollLockReturn, type UseSlottedContextProps, type UseSlottedContextReturn, type UseStyleInjectionOptions, type UseSyntheticBlurEventOptions, type UseSyntheticBlurEventReturn, VALID_VALIDITY_STATE, type Validation, type ValidationError, type ValidationErrors, type ValidationFunction, type ValidationResult, getInteractionModality, mergeValidation, privateValidationStateProp, useAnimation, useAriaProps, useCollectionNavigation, useContextProps, useEffectEvent, useElementVisibility, useFocus, useFocusRing, useFocusVisible, useFocusVisibleListener, useFocusWithin, useFocusable, useFormState, useGlobalListeners, useHover, useId, useIsomorphicInsertionEffect, useKeyboard, useLatestRef, useLongPress, useMounted, usePress, useRenderer, useScrollLock, useSlottedContext, useStyleInjection, useSupported, useSyntheticBlurEvent };