@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
314 lines • 8.45 kB
TypeScript
/**
* Reactive localStorage with automatic serialization.
*
* @example
* ```typescript
* const theme = useLocalStorage('theme', 'dark')
* console.log(theme.value) // 'dark'
* theme.value = 'light' // automatically saved
* ```
*/
export declare function useLocalStorage<T>(key: string, defaultValue: T): { value: T; remove: () => void };
/**
* Reactive sessionStorage with automatic serialization.
*
* @example
* ```typescript
* const token = useSessionStorage('auth_token', null)
* ```
*/
export declare function useSessionStorage<T>(key: string, defaultValue: T): { value: T; remove: () => void };
/**
* Add an event listener with automatic cleanup.
*
* @example
* ```typescript
* useEventListener('resize', () => console.log('resized'))
* useEventListener(buttonRef, 'click', () => console.log('clicked'))
* ```
*/
export declare function useEventListener<K extends keyof WindowEventMap>(event: K, handler: (e: WindowEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
export declare function useEventListener<K extends keyof DocumentEventMap>(target: Document, event: K, handler: (e: DocumentEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
export declare function useEventListener<K extends keyof HTMLElementEventMap>(target: MaybeRef<HTMLElement | null>, event: K, handler: (e: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions): () => void;
export declare function useEventListener(...args: any[]): () => void;
/**
* Detect clicks outside an element.
*
* @example
* ```typescript
* const dropdownRef = ref<HTMLElement>()
* useClickOutside(dropdownRef, () => {
* isOpen.value = false
* })
* ```
*/
export declare function useClickOutside(target: MaybeRef<HTMLElement | null>, handler: (event: MouseEvent) => void): () => void;
/**
* Reactive window size.
*
* @example
* ```typescript
* const { width, height } = useWindowSize()
* console.log(`${width.value}x${height.value}`)
* ```
*/
export declare function useWindowSize(): {
width: { readonly value: number }
height: { readonly value: number }
};
/**
* Reactive media query.
*
* @example
* ```typescript
* const isMobile = useMediaQuery('(max-width: 768px)')
* const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
* ```
*/
export declare function useMediaQuery(query: string): { readonly value: boolean };
/**
* Common breakpoint helpers.
*
* @example
* ```typescript
* const { isMobile, isTablet, isDesktop } = useBreakpoints()
* ```
*/
export declare function useBreakpoints(): void;
/**
* Detect dark mode preference.
*
* @example
* ```typescript
* const isDark = usePrefersDark()
* ```
*/
export declare function usePrefersDark(): { readonly value: boolean };
/**
* Reactive online/offline status.
*
* @example
* ```typescript
* const isOnline = useOnline()
* if (!isOnline.value) showOfflineWarning()
* ```
*/
export declare function useOnline(): { readonly value: boolean };
/**
* Reactive mouse position.
*
* @example
* ```typescript
* const { x, y } = useMouse()
* ```
*/
export declare function useMouse(): {
x: { readonly value: number }
y: { readonly value: number }
};
/**
* Reactive scroll position.
*
* @example
* ```typescript
* const { x, y } = useScroll()
* // Or for a specific element
* const { x, y } = useScroll(containerRef)
* ```
*/
export declare function useScroll(target?: MaybeRef<HTMLElement | null>): {
x: { readonly value: number }
y: { readonly value: number }
isScrolling: { readonly value: boolean }
};
/**
* Debounce a function.
*
* @example
* ```typescript
* const debouncedSearch = useDebounce((query: string) => {
* fetchResults(query)
* }, 300)
* ```
*/
export declare function useDebounce<T extends (...args: any[]) => any>(fn: T, delay: number): (...args: Parameters<T>) => void;
/**
* Debounce a value.
*
* @example
* ```typescript
* const searchQuery = ref('')
* const debouncedQuery = useDebouncedValue(() => searchQuery.value, 300)
* ```
*/
export declare function useDebouncedValue<T>(getter: () => T, delay: number): { readonly value: T };
/**
* Throttle a function.
*
* @example
* ```typescript
* const throttledScroll = useThrottle(() => {
* updateHeader()
* }, 100)
* ```
*/
export declare function useThrottle<T extends (...args: any[]) => any>(fn: T, limit: number): (...args: Parameters<T>) => void;
/**
* Reactive interval.
*
* @example
* ```typescript
* const { counter, pause, resume, reset } = useInterval(1000)
* ```
*/
export declare function useInterval(interval: number, options?: { immediate?: boolean }): {
counter: { readonly value: number }
pause: () => void
resume: () => void
reset: () => void
};
/**
* One-time timeout with controls.
*
* @example
* ```typescript
* const { isPending, start, stop } = useTimeout(() => {
* showNotification()
* }, 5000)
* ```
*/
export declare function useTimeout(callback: () => void, delay: number): {
isPending: { readonly value: boolean }
start: () => void
stop: () => void
};
/**
* Boolean toggle.
*
* @example
* ```typescript
* const [isOpen, toggle, setOpen] = useToggle(false)
* toggle() // true
* setOpen(false) // false
* ```
*/
export declare function useToggle(initial?: any): [{ value: boolean }, () => void, (value: boolean) => void];
/**
* Counter with controls.
*
* @example
* ```typescript
* const { count, inc, dec, set, reset } = useCounter(0)
* inc() // 1
* inc(5) // 6
* dec() // 5
* ```
*/
export declare function useCounter(initial?: any, options?: { min?: number; max?: number }): {
count: { value: number }
inc: (delta?: number) => void
dec: (delta?: number) => void
set: (value: number) => void
reset: () => void
};
/**
* Clipboard access.
*
* @example
* ```typescript
* const { copy, copied, text } = useClipboard()
* await copy('Hello!')
* if (copied.value) showToast('Copied!')
* ```
*/
export declare function useClipboard(): {
text: { readonly value: string }
copied: { readonly value: boolean }
copy: (text: string) => Promise<void>
read: () => Promise<string>
};
/**
* Document title.
*
* @example
* ```typescript
* const title = useTitle('My App')
* title.value = 'New Page - My App'
* ```
*/
export declare function useTitle(initial?: string): { value: string };
/**
* Element visibility with IntersectionObserver.
*
* @example
* ```typescript
* const target = ref<HTMLElement>()
* const { isVisible } = useIntersectionObserver(target)
* ```
*/
export declare function useIntersectionObserver(target: MaybeRef<HTMLElement | null>, options?: IntersectionObserverInit): {
isVisible: { readonly value: boolean }
stop: () => void
};
/**
* Focus state of an element.
*
* @example
* ```typescript
* const inputRef = ref<HTMLInputElement>()
* const { isFocused } = useFocus(inputRef)
* ```
*/
export declare function useFocus(target: MaybeRef<HTMLElement | null>): {
isFocused: { readonly value: boolean }
focus: () => void
blur: () => void
};
/**
* Fetch data with reactive state.
*
* @example
* ```typescript
* const { data, error, isLoading } = useFetch('/api/users')
*
* // With options
* const { data, execute } = useFetch('/api/user', {
* immediate: false
* })
* await execute()
* ```
*/
export declare function useFetch<T = unknown>(url: string | (() => string), options?: UseFetchOptions<T> & RequestInit): UseFetchReturn<T>;
/**
* Async state management.
*
* @example
* ```typescript
* const { state, isLoading, error, execute } = useAsync(async () => {
* const res = await fetch('/api/data')
* return res.json()
* })
* ```
*/
export declare function useAsync<T>(fn: () => Promise<T>, options?: { immediate?: boolean }): {
state: { readonly value: T | null }
isLoading: { readonly value: boolean }
error: { readonly value: Error | null }
execute: () => Promise<T | null>
};
declare interface UseFetchOptions<T> {
immediate?: boolean
initialData?: T
refetch?: boolean
}
declare interface UseFetchReturn<T> {
data: { readonly value: T | null }
error: { readonly value: Error | null }
isLoading: { readonly value: boolean }
execute: () => Promise<void>
abort: () => void
}
// =============================================================================
// Types
// =============================================================================
declare type MaybeRef<T> = T | { value: T }