@stacksjs/stx/dist/composables/use-intersection-observer.d.ts

A performant UI Framework. Powered by Bun.

/**
 * Observe element intersection with viewport or container
 */
export declare function useIntersectionObserver(target: Element | (() => Element | null) | null, callback?: IntersectionCallback, options?: IntersectionObserverOptions): IntersectionObserverRef;
/**
 * Simple visibility check - returns true when element is in viewport
 */
export declare function useElementVisibility(target: Element | (() => Element | null) | null, options?: Omit<IntersectionObserverOptions, 'once'>): {
  get: () => boolean
  subscribe: (fn: (visible: boolean) => void) => () => void
};
/**
 * Lazy load handler - triggers callback once when element becomes visible
 */
export declare function useLazyLoad(target: Element | (() => Element | null) | null, onVisible: () => void, options?: Omit<IntersectionObserverOptions, 'once'>): { stop: () => void };
/**
 * Infinite scroll handler - triggers callback when sentinel element is visible
 */
export declare function useInfiniteScroll(sentinel: Element | (() => Element | null) | null, loadMore: () => void | Promise<void>, options?: IntersectionObserverOptions & {
    /** Debounce time in ms */
    debounce?: number
  }): {
  stop: () => void
  start: () => void
  isLoading: () => boolean
};
/**
 * Track multiple elements' visibility
 */
export declare function useIntersectionObserverMultiple(targets: Element[] | (() => Element[]), callback: (entries: IntersectionObserverEntry[], observer: IntersectionObserver) => void, options?: Omit<IntersectionObserverOptions, 'once'>): {
  stop: () => void
  start: () => void
  observe: (element: Element) => void
  unobserve: (element: Element) => void
};
/**
 * useIntersectionObserver - Reactive Intersection Observer API
 *
 * Track element visibility for lazy loading, infinite scroll, and animations.
 *
 * @example
 * ```ts
 * // Basic visibility tracking
 * const { isVisible, stop } = useIntersectionObserver(element)
 *
 * // Lazy loading images
 * useIntersectionObserver(imgElement, (entry) => {
 *   if (entry.isIntersecting) {
 *     imgElement.src = imgElement.dataset.src
 *   }
 * }, { once: true })
 *
 * // Infinite scroll
 * useIntersectionObserver(sentinelElement, () => {
 *   loadMoreItems()
 * }, { rootMargin: '100px' })
 * ```
 */
export declare interface IntersectionObserverOptions {
  root?: Element | Document | null
  rootMargin?: string
  threshold?: number | number[]
  once?: boolean
  immediate?: boolean
}
export declare interface IntersectionState {
  isIntersecting: boolean
  intersectionRatio: number
  boundingClientRect: DOMRectReadOnly | null
  intersectionRect: DOMRectReadOnly | null
  isVisible: boolean
  entry: IntersectionObserverEntry | null
}
export declare interface IntersectionObserverRef {
  get: () => IntersectionState
  subscribe: (fn: (state: IntersectionState) => void) => () => void
  isVisible: () => boolean
  stop: () => void
  start: () => void
}
declare type IntersectionCallback = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void