@stacksjs/stx
Version:
A performant UI Framework. Powered by Bun.
103 lines • 3.51 kB
TypeScript
/**
* Creates a virtual scroll instance for a list of items
*/
export declare function createVirtualList<T>(items: T[], options: VirtualListOptions): VirtualScrollInstance;
/**
* Process @virtualList directives in templates
*/
export declare function processVirtualListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
/**
* Generate CSS for virtual list styling
*/
export declare function generateVirtualListCSS(): string;
/**
* Hook to create a reactive virtual list
*/
export declare function useVirtualList<T>(items: () => T[], options: VirtualListOptions): {
visibleItems: () => T[]
totalHeight: () => number
containerProps: () => Record<string, unknown>
itemProps: (index: number) => Record<string, unknown>
scrollToIndex: (index: number) => void
};
/**
* Process @infiniteList directives for infinite scrolling
*/
export declare function processInfiniteListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
/**
* Process @virtualGrid directives for grid virtualization
*/
export declare function processVirtualGridDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
/**
* Virtual Scrolling Module
*
* Provides efficient rendering of large lists using windowing/virtualization.
* Only renders items that are visible in the viewport, dramatically improving
* performance for lists with thousands of items.
*
* @example
* ```html
* @virtualList(items, { itemHeight: 50, containerHeight: 400 })
* <div class="item">{{ item.name }}</div>
* @endvirtualList
* ```
*/
// ============================================================================
// Types
// ============================================================================
export declare interface VirtualListOptions {
itemHeight: number
containerHeight: number
overscan?: number
keyProperty?: string
dynamicHeight?: boolean
estimatedItemHeight?: number
scrollBehavior?: 'auto' | 'smooth'
direction?: 'vertical' | 'horizontal'
containerClass?: string
viewportClass?: string
itemClass?: string
}
export declare interface VirtualListState {
startIndex: number
endIndex: number
scrollTop: number
totalHeight: number
visibleItems: unknown[]
itemHeights: Map<number, number>
}
export declare interface VirtualScrollInstance {
scrollToIndex: (index: number, behavior?: ScrollBehavior) => void
scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void
getState: () => VirtualListState
refresh: () => void
setItems: (items: unknown[]) => void
destroy: () => void
}
// ============================================================================
// Infinite Scroll Support
// ============================================================================
export declare interface InfiniteScrollOptions extends VirtualListOptions {
threshold?: number
onLoadMore?: () => Promise<void>
hasMore?: boolean
isLoading?: boolean
}
// ============================================================================
// Grid Virtualization
// ============================================================================
export declare interface VirtualGridOptions {
columns: number
rowHeight: number
containerHeight: number
gap?: number
overscan?: number
}
export default {
createVirtualList,
processVirtualListDirectives,
processInfiniteListDirectives,
processVirtualGridDirectives,
generateVirtualListCSS,
useVirtualList,
};