@dreamstack-us/section-flow 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,866 @@
+import React$1 from 'react';
+import { ScrollViewProps, StyleProp, ViewStyle, Animated, View, LayoutChangeEvent, NativeSyntheticEvent, NativeScrollEvent } from 'react-native';
+
+/**
+* Core Types
+*/
+interface LayoutRect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+interface Section<TItem> {
+	key: string;
+	title?: string;
+	data: TItem[];
+}
+/**
+* Flattened item types for internal processing
+*/
+type FlattenedItemType = "section-header" | "item" | "section-footer";
+interface FlattenedItem<TItem> {
+	type: FlattenedItemType;
+	key: string;
+	sectionKey: string;
+	sectionIndex: number;
+	itemIndex: number;
+	item: TItem | null;
+	section: Section<TItem>;
+}
+/**
+* Render info passed to render functions
+*/
+interface RenderItemInfo<TItem> {
+	item: TItem;
+	index: number;
+	section: Section<TItem>;
+	sectionIndex: number;
+}
+interface RenderSectionHeaderInfo<TItem> {
+	section: Section<TItem>;
+	sectionIndex: number;
+}
+interface RenderSectionFooterInfo<TItem> {
+	section: Section<TItem>;
+	sectionIndex: number;
+}
+/**
+* Viewability types
+*/
+interface ViewToken<TItem> {
+	item: TItem | null;
+	key: string;
+	index: number;
+	isViewable: boolean;
+	section: Section<TItem>;
+}
+interface ViewabilityConfig {
+	minimumViewTime?: number;
+	viewAreaCoveragePercentThreshold?: number;
+	itemVisiblePercentThreshold?: number;
+	waitForInteraction?: boolean;
+}
+interface ViewabilityConfigCallbackPair<TItem> {
+	viewabilityConfig: ViewabilityConfig;
+	onViewableItemsChanged: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void;
+}
+/**
+* Cell recycling types
+*/
+interface RecycledCell {
+	key: string;
+	itemType: string;
+	flatIndex: number;
+}
+interface RecyclePool {
+	type: string;
+	cells: RecycledCell[];
+	maxSize: number;
+}
+/**
+* Section layout types
+*/
+interface SectionLayoutInfo {
+	sectionKey: string;
+	sectionIndex: number;
+	headerLayout: LayoutRect;
+	footerLayout: LayoutRect | null;
+	itemsStartOffset: number;
+	itemsEndOffset: number;
+	itemCount: number;
+	isCollapsed: boolean;
+}
+/**
+* Scroll types
+*/
+interface ScrollToSectionOptions {
+	sectionKey?: string;
+	sectionIndex?: number;
+	animated?: boolean;
+	viewPosition?: number;
+}
+interface ScrollToItemOptions {
+	sectionKey?: string;
+	sectionIndex?: number;
+	itemIndex: number;
+	animated?: boolean;
+	viewPosition?: number;
+}
+/**
+* Main component props
+*/
+interface SectionFlowProps<TItem> extends Omit<ScrollViewProps, "children"> {
+	sections: Section<TItem>[];
+	renderItem: (info: RenderItemInfo<TItem>) => React.ReactElement | null;
+	renderSectionHeader?: (info: RenderSectionHeaderInfo<TItem>) => React.ReactElement | null;
+	renderSectionFooter?: (info: RenderSectionFooterInfo<TItem>) => React.ReactElement | null;
+	keyExtractor?: (item: TItem, index: number) => string;
+	getItemType?: (item: TItem, index: number, section: Section<TItem>) => string;
+	estimatedItemSize?: number;
+	estimatedSectionHeaderSize?: number;
+	estimatedSectionFooterSize?: number;
+	horizontal?: boolean;
+	stickySectionHeadersEnabled?: boolean;
+	stickyHeaderStyle?: StyleProp<ViewStyle>;
+	collapsible?: boolean;
+	defaultCollapsed?: string[];
+	onSectionToggle?: (sectionKey: string, collapsed: boolean) => void;
+	maxItemsInRecyclePool?: number;
+	drawDistance?: number;
+	viewabilityConfig?: ViewabilityConfig;
+	onViewableItemsChanged?: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void;
+	viewabilityConfigCallbackPairs?: ViewabilityConfigCallbackPair<TItem>[];
+	onEndReached?: (info: {
+		distanceFromEnd: number
+	}) => void;
+	onEndReachedThreshold?: number;
+	onScrollBeginDrag?: ScrollViewProps["onScrollBeginDrag"];
+	onScrollEndDrag?: ScrollViewProps["onScrollEndDrag"];
+	onMomentumScrollBegin?: ScrollViewProps["onMomentumScrollBegin"];
+	onMomentumScrollEnd?: ScrollViewProps["onMomentumScrollEnd"];
+	style?: StyleProp<ViewStyle>;
+	contentContainerStyle?: StyleProp<ViewStyle>;
+	ListHeaderComponent?: React.ComponentType | React.ReactElement | null;
+	ListFooterComponent?: React.ComponentType | React.ReactElement | null;
+	ListEmptyComponent?: React.ComponentType | React.ReactElement | null;
+	ItemSeparatorComponent?: React.ComponentType<{
+		section: Section<TItem>
+		leadingItem: TItem
+	}> | null;
+	SectionSeparatorComponent?: React.ComponentType<{
+		section: Section<TItem>
+		leadingSection: Section<TItem> | null
+		trailingSection: Section<TItem> | null
+	}> | null;
+	refreshing?: boolean;
+	onRefresh?: () => void;
+	extraData?: unknown;
+	debug?: boolean;
+}
+/**
+* Ref methods
+*/
+interface SectionFlowRef<TItem = unknown> {
+	scrollToSection: (options: ScrollToSectionOptions) => void;
+	scrollToItem: (options: ScrollToItemOptions) => void;
+	scrollToOffset: (options: {
+		offset: number
+		animated?: boolean
+	}) => void;
+	scrollToEnd: (options?: {
+		animated?: boolean
+	}) => void;
+	toggleSection: (sectionKey: string) => void;
+	getSectionLayouts: () => SectionLayoutInfo[];
+	getVisibleItems: () => ViewToken<TItem>[];
+	recordInteraction: () => void;
+	flashScrollIndicators: () => void;
+}
+/**
+* Layout positioner interface (for future layout strategies)
+*/
+interface LayoutPositioner {
+	getLayoutForIndex(index: number): LayoutRect;
+	getContentSize(): {
+		width: number
+		height: number
+	};
+	getVisibleRange(scrollOffset: number, viewportSize: number, overscan: number): {
+		startIndex: number
+		endIndex: number
+	};
+	updateItemLayout(index: number, layout: LayoutRect): void;
+	invalidateFrom(index: number): void;
+	getIndexForOffset(offset: number): number;
+	getTotalItemCount(): number;
+}
+/**
+* Cell recycler interface
+*/
+interface CellRecyclerInterface {
+	acquireCell(type: string, flatIndex: number): RecycledCell | null;
+	releaseCell(cell: RecycledCell): void;
+	clearPools(): void;
+	setMaxPoolSize(type: string, size: number): void;
+	getPoolStats(): Map<string, {
+		available: number
+		inUse: number
+	}>;
+}
+/**
+* Viewability tracker interface
+*/
+interface ViewabilityTrackerInterface<TItem> {
+	updateScrollOffset(offset: number): void;
+	getVisibleIndices(): number[];
+	isIndexVisible(index: number): boolean;
+	getFirstVisibleIndex(): number;
+	getLastVisibleIndex(): number;
+	onViewableItemsChanged(callback: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void): () => void;
+}
+
+/**
+* Export with proper generic typing.
+* Usage: <SectionFlow<MyItemType> sections={...} renderItem={...} />
+*/
+declare const SectionFlow: <TItem>(props: SectionFlowProps<TItem> & {
+	ref?: React$1.ForwardedRef<SectionFlowRef<TItem>>
+}) => React$1.ReactElement;
+
+interface RecyclerCellProps {
+	cell: RecycledCell;
+	layout: LayoutRect;
+	children: React$1.ReactNode;
+	onLayout: (key: string, flatIndex: number, layout: LayoutRect) => void;
+	debug?: boolean;
+}
+/**
+* RecyclerCell wraps each item with absolute positioning.
+* This is the fundamental unit of the recycling system.
+*
+* Key responsibilities:
+* 1. Position the item at the correct x/y coordinates
+* 2. Report layout measurements back to the system
+* 3. Maintain stable identity for recycling (via key)
+*/
+declare function RecyclerCellComponent({ cell, layout, children, onLayout, debug }: RecyclerCellProps): React$1.ReactElement;
+/**
+* Memoized cell component to prevent unnecessary re-renders.
+* Only re-renders when:
+* - Cell key changes (different item)
+* - Layout position changes
+* - Children change (new render)
+*/
+declare const RecyclerCell: React$1.MemoExoticComponent<typeof RecyclerCellComponent>;
+
+interface RecyclerContainerProps<TItem> {
+	flattenedData: FlattenedItem<TItem>[];
+	visibleRange: {
+		startIndex: number
+		endIndex: number
+	};
+	getLayoutForIndex: (index: number) => LayoutRect;
+	getCell: (flatIndex: number) => RecycledCell;
+	contentSize: {
+		width: number
+		height: number
+	};
+	renderItem: (info: RenderItemInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionHeader?: (info: RenderSectionHeaderInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionFooter?: (info: RenderSectionFooterInfo<TItem>) => React$1.ReactElement | null;
+	onCellLayout: (key: string, flatIndex: number, layout: LayoutRect) => void;
+	horizontal?: boolean;
+	debug?: boolean;
+}
+/**
+* RecyclerContainer manages the absolute-positioned content area.
+* It renders only the visible items within the current scroll window.
+*
+* Key responsibilities:
+* 1. Set content size for scroll container
+* 2. Render visible items at correct positions
+* 3. Coordinate cell recycling
+*/
+declare function RecyclerContainerComponent<TItem>({ flattenedData, visibleRange, getLayoutForIndex, getCell, contentSize, renderItem, renderSectionHeader, renderSectionFooter, onCellLayout, horizontal, debug }: RecyclerContainerProps<TItem>): React$1.ReactElement;
+declare const RecyclerContainer: typeof RecyclerContainerComponent;
+
+interface SectionHeaderProps<TItem> {
+	section: Section<TItem>;
+	sectionIndex: number;
+	isCollapsed?: boolean;
+	collapsible?: boolean;
+	onToggle?: (sectionKey: string) => void;
+	renderContent?: (info: {
+		section: Section<TItem>
+		sectionIndex: number
+		isCollapsed: boolean
+	}) => React$1.ReactElement | null;
+	style?: ViewStyle;
+}
+/**
+* Default section header component.
+* Can be overridden by providing renderSectionHeader prop to SectionFlow.
+*/
+declare function SectionHeaderComponent<TItem>({ section, sectionIndex, isCollapsed, collapsible, onToggle, renderContent, style }: SectionHeaderProps<TItem>): React$1.ReactElement;
+declare const SectionHeader: typeof SectionHeaderComponent;
+
+interface StickyHeaderContainerProps<TItem> {
+	stickySection: SectionLayoutInfo | null;
+	translateY: number;
+	sections: Section<TItem>[];
+	renderSectionHeader: (info: RenderSectionHeaderInfo<TItem>) => React$1.ReactElement | null;
+	horizontal?: boolean;
+	style?: ViewStyle;
+}
+/**
+* Container for the sticky section header.
+* Positioned at the top (or left for horizontal) of the viewport.
+* Handles the "push" effect when the next section approaches.
+*/
+declare function StickyHeaderContainerComponent<TItem>({ stickySection, translateY, sections, renderSectionHeader, horizontal, style }: StickyHeaderContainerProps<TItem>): React$1.ReactElement | null;
+declare const StickyHeaderContainer: typeof StickyHeaderContainerComponent;
+/**
+* Animated version of sticky header for smoother transitions.
+* Uses Animated API for better performance on the native thread.
+*/
+interface AnimatedStickyHeaderProps<TItem> extends StickyHeaderContainerProps<TItem> {
+	animatedTranslateY: Animated.Value;
+}
+declare function AnimatedStickyHeaderContainerComponent<TItem>({ stickySection, animatedTranslateY, sections, renderSectionHeader, horizontal, style }: AnimatedStickyHeaderProps<TItem>): React$1.ReactElement | null;
+declare const AnimatedStickyHeaderContainer: typeof AnimatedStickyHeaderContainerComponent;
+
+interface UseMeasurementOptions {
+	onMeasure: (layout: LayoutRect) => void;
+	enabled?: boolean;
+}
+interface MeasurementResult {
+	ref: React.RefObject<View | null>;
+	onLayout: (event: LayoutChangeEvent) => void;
+	measure: () => void;
+}
+/**
+* Hook for synchronous layout measurement using New Architecture features.
+*
+* In React Native's New Architecture with Fabric, useLayoutEffect runs synchronously
+* before paint, allowing us to measure and correct layouts without visible glitches.
+*
+* This hook provides:
+* 1. A ref to attach to the View
+* 2. An onLayout callback for initial/resize measurements
+* 3. A measure function for on-demand measurement
+*/
+declare function useLayoutMeasurement(options: UseMeasurementOptions): MeasurementResult;
+/**
+* Hook for measuring a cell's layout and reporting to the layout system.
+* Uses synchronous measurement in New Architecture for smooth corrections.
+*/
+declare function useCellMeasurement(cellKey: string, onCellMeasured: (key: string, layout: LayoutRect) => void, enabled?: boolean): MeasurementResult;
+/**
+* Hook for progressive rendering - measures initial items and expands.
+* Implements FlashList v2's progressive rendering strategy.
+*/
+declare function useProgressiveRender(totalItems: number, initialCount: number, batchSize: number, onRenderCountChange: (count: number) => void): {
+	renderCount: number
+	onItemMeasured: (index: number) => void
+};
+
+interface ScrollState {
+	offset: number;
+	velocity: number;
+	direction: "forward" | "backward" | "idle";
+	isScrolling: boolean;
+	contentSize: number;
+	viewportSize: number;
+}
+interface UseScrollHandlerOptions {
+	horizontal?: boolean;
+	onScrollStateChange?: (state: ScrollState) => void;
+	onEndReached?: (distanceFromEnd: number) => void;
+	onEndReachedThreshold?: number;
+}
+interface ScrollHandlerResult {
+	scrollState: React.RefObject<ScrollState>;
+	onScroll: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+	onScrollBeginDrag: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+	onScrollEndDrag: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+	onMomentumScrollBegin: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+	onMomentumScrollEnd: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+	onContentSizeChange: (width: number, height: number) => void;
+}
+/**
+* Hook for tracking scroll state with velocity and direction detection.
+* Used for adaptive buffering and scroll optimization.
+*/
+declare function useScrollHandler(options?: UseScrollHandlerOptions): ScrollHandlerResult;
+/**
+* Hook to calculate adaptive draw distance based on scroll velocity.
+* Increases buffer for fast scrolling to reduce blank areas.
+*/
+declare function useAdaptiveDrawDistance(baseDistance: number, scrollVelocity: number): number;
+
+interface UseRecyclerOptions<TItem> {
+	flattenedData: FlattenedItem<TItem>[];
+	getItemType?: (item: TItem, index: number) => string;
+	maxPoolSize?: number;
+}
+interface RecyclerResult {
+	getCell: (flatIndex: number) => RecycledCell;
+	releaseCell: (cell: RecycledCell) => void;
+	updateVisibleRange: (startIndex: number, endIndex: number) => void;
+	clearPools: () => void;
+	getPoolStats: () => Map<string, {
+		available: number
+		inUse: number
+	}>;
+}
+/**
+* Hook for managing cell recycling state.
+* Provides methods to acquire and release cells based on visibility.
+*/
+declare function useRecycler<TItem>(options: UseRecyclerOptions<TItem>): RecyclerResult;
+/**
+* Hook to determine which item type to use for rendering.
+* Returns a stable function that maps flat indices to type strings.
+*/
+declare function useItemTypeResolver<TItem>(flattenedData: FlattenedItem<TItem>[], getItemType?: (item: TItem, index: number) => string): (flatIndex: number) => string;
+
+interface StickyHeaderState {
+	sectionKey: string | null;
+	sectionIndex: number;
+	translateY: number;
+	isSticky: boolean;
+	headerLayout: LayoutRect | null;
+}
+interface UseStickyHeaderOptions {
+	sectionLayouts: SectionLayoutInfo[];
+	scrollOffset: number;
+	viewportHeight: number;
+	horizontal?: boolean;
+	enabled?: boolean;
+}
+/**
+* Hook for computing sticky header positioning.
+* Handles the "pushing" effect when the next section header approaches.
+*/
+declare function useStickyHeader(options: UseStickyHeaderOptions): StickyHeaderState;
+/**
+* Hook for tracking multiple sticky headers (e.g., for multi-level sections).
+*/
+declare function useMultipleStickyHeaders(sectionLayouts: SectionLayoutInfo[], scrollOffset: number, levels?: number): StickyHeaderState[];
+/**
+* Hook for determining sticky header opacity during transitions.
+*/
+declare function useStickyHeaderOpacity(stickyState: StickyHeaderState, fadeDistance?: number): number;
+
+interface UseViewabilityOptions<TItem> {
+	flattenedData: FlattenedItem<TItem>[];
+	layoutPositioner: LayoutPositioner;
+	scrollOffset: number;
+	viewportSize: number;
+	horizontal?: boolean;
+	viewabilityConfig?: ViewabilityConfig;
+	onViewableItemsChanged?: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void;
+}
+interface ViewabilityResult<TItem> {
+	visibleIndices: number[];
+	firstVisibleIndex: number;
+	lastVisibleIndex: number;
+	getVisibleItems: () => ViewToken<TItem>[];
+	recordInteraction: () => void;
+}
+/**
+* Hook for tracking item viewability and triggering callbacks.
+*/
+declare function useViewability<TItem>(options: UseViewabilityOptions<TItem>): ViewabilityResult<TItem>;
+/**
+* Hook for handling multiple viewability configs with different callbacks.
+*/
+declare function useMultipleViewabilityConfigs<TItem>(flattenedData: FlattenedItem<TItem>[], layoutPositioner: LayoutPositioner, scrollOffset: number, viewportSize: number, configs: Array<{
+	viewabilityConfig: ViewabilityConfig
+	onViewableItemsChanged: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void
+}>, horizontal?: boolean): void;
+
+/**
+* LayoutCache stores measured layout information for items.
+* This is used for:
+* 1. Caching measured sizes to avoid re-measurement
+* 2. Tracking which items have been measured vs estimated
+* 3. Computing average sizes per item type for better predictions
+*/
+interface LayoutCache {
+	get(key: string): LayoutRect | undefined;
+	set(key: string, layout: LayoutRect): void;
+	has(key: string): boolean;
+	delete(key: string): void;
+	clear(): void;
+	invalidateFrom(flatIndex: number, keyToIndexMap: Map<string, number>): void;
+	getAverageSize(itemType: string): number | undefined;
+	recordMeasurement(itemType: string, size: number): void;
+	size: number;
+}
+/**
+* Factory function to create a LayoutCache instance.
+*/
+declare function createLayoutCache(): LayoutCache;
+
+interface LinearLayoutPositionerOptions {
+	horizontal?: boolean;
+	estimatedItemSize?: number;
+	estimatedHeaderSize?: number;
+	estimatedFooterSize?: number;
+	containerWidth?: number;
+	containerHeight?: number;
+}
+/**
+* LinearLayoutPositioner implements the LayoutPositioner interface for
+* standard vertical or horizontal list layouts.
+*
+* It computes absolute positions for each item based on:
+* 1. Measured sizes from LayoutCache (when available)
+* 2. Estimated sizes (when not yet measured)
+* 3. Type-specific size predictions
+*/
+declare class LinearLayoutPositioner implements LayoutPositioner {
+	private horizontal;
+	private estimatedItemSize;
+	private estimatedHeaderSize;
+	private estimatedFooterSize;
+	private containerWidth;
+	private containerHeight;
+	private flattenedData;
+	private layoutCache;
+	private getItemType;
+	private computedLayouts;
+	private totalContentSize;
+	private layoutsValid;
+	constructor(layoutCache: LayoutCache, getItemType: (flatIndex: number) => string, options?: LinearLayoutPositionerOptions);
+	/**
+	* Update the flattened data and invalidate layouts.
+	*/
+	setData(flattenedData: FlattenedItem<unknown>[]): void;
+	/**
+	* Update container dimensions.
+	*/
+	setContainerSize(width: number, height: number): void;
+	/**
+	* Get the estimated size for an item based on its type.
+	*/
+	private getEstimatedSize;
+	/**
+	* Get the actual or estimated size for an item.
+	*/
+	private getItemSize;
+	/**
+	* Compute layouts for all items if not already computed.
+	*/
+	private ensureLayoutsComputed;
+	/**
+	* Get the layout for a specific index.
+	*/
+	getLayoutForIndex(index: number): LayoutRect;
+	/**
+	* Get the total content size.
+	*/
+	getContentSize(): {
+		width: number
+		height: number
+	};
+	/**
+	* Get the range of visible indices for the given scroll position.
+	* Uses binary search for efficiency with large lists.
+	*/
+	getVisibleRange(scrollOffset: number, viewportSize: number, overscan: number): {
+		startIndex: number
+		endIndex: number
+	};
+	/**
+	* Binary search to find first item that ends after the given offset.
+	*/
+	private binarySearchStart;
+	/**
+	* Binary search to find last item that starts before the given offset.
+	*/
+	private binarySearchEnd;
+	/**
+	* Update the layout for a specific index after measurement.
+	*/
+	updateItemLayout(index: number, layout: LayoutRect): void;
+	/**
+	* Invalidate layouts from a given index.
+	*/
+	invalidateFrom(index: number): void;
+	/**
+	* Invalidate all layouts.
+	*/
+	invalidateAll(): void;
+	/**
+	* Get the index of the item at or just before the given offset.
+	*/
+	getIndexForOffset(offset: number): number;
+	/**
+	* Get the total number of items.
+	*/
+	getTotalItemCount(): number;
+}
+/**
+* Factory function to create a LinearLayoutPositioner.
+*/
+declare function createLayoutPositioner(layoutCache: LayoutCache, getItemType: (flatIndex: number) => string, options?: LinearLayoutPositionerOptions): LinearLayoutPositioner;
+
+/**
+* CellRecycler manages pools of recycled cell instances per item type.
+* This is the core of FlashList-style performance - reusing view components
+* instead of destroying and recreating them.
+*/
+declare class CellRecyclerImpl implements CellRecyclerInterface {
+	private pools;
+	private inUse;
+	private defaultMaxPoolSize;
+	private cellCounter;
+	constructor(defaultMaxPoolSize?: number);
+	/**
+	* Acquire a cell from the pool for the given type.
+	* Returns null if no recycled cells are available (caller should create new).
+	*/
+	acquireCell(type: string, flatIndex: number): RecycledCell | null;
+	/**
+	* Release a cell back to its pool for recycling.
+	*/
+	releaseCell(cell: RecycledCell): void;
+	/**
+	* Clear all recycled cells from all pools.
+	* Useful when data changes significantly.
+	*/
+	clearPools(): void;
+	/**
+	* Set the maximum pool size for a specific item type.
+	*/
+	setMaxPoolSize(type: string, size: number): void;
+	/**
+	* Get statistics about pool usage for debugging.
+	*/
+	getPoolStats(): Map<string, {
+		available: number
+		inUse: number
+	}>;
+	/**
+	* Generate a unique key for a new cell.
+	*/
+	generateCellKey(type: string): string;
+	/**
+	* Create a new cell (when pool is empty).
+	*/
+	createCell(type: string, flatIndex: number): RecycledCell;
+	/**
+	* Get or create a cell - the main method used during rendering.
+	* First tries to acquire from pool, then creates new if needed.
+	*/
+	getCell(type: string, flatIndex: number): RecycledCell;
+}
+/**
+* Factory function to create a CellRecycler instance.
+*/
+declare function createCellRecycler(defaultMaxPoolSize?: number): CellRecyclerImpl;
+
+/**
+* ViewabilityTracker monitors which items are currently visible in the viewport
+* and triggers callbacks when viewability changes.
+*/
+interface ViewabilityTracker<TItem> {
+	updateScrollOffset(offset: number): void;
+	setViewportSize(size: number): void;
+	setData(flattenedData: FlattenedItem<TItem>[]): void;
+	getVisibleIndices(): number[];
+	isIndexVisible(index: number): boolean;
+	getFirstVisibleIndex(): number;
+	getLastVisibleIndex(): number;
+	onViewableItemsChanged(callback: (info: {
+		viewableItems: ViewToken<TItem>[]
+		changed: ViewToken<TItem>[]
+	}) => void): () => void;
+	recordInteraction(): void;
+	dispose(): void;
+}
+/**
+* Factory function to create a ViewabilityTracker.
+*/
+declare function createViewabilityTracker<TItem>(layoutPositioner: LayoutPositioner, flattenedData: FlattenedItem<TItem>[], config?: ViewabilityConfig, horizontal?: boolean): ViewabilityTracker<TItem>;
+
+/**
+* SectionLayoutManager provides section-aware layout operations on top of
+* the LinearLayoutPositioner. It handles:
+* - Mapping between section/item coordinates and flat indices
+* - Tracking section boundaries and layouts
+* - Managing collapsed section state
+*/
+interface SectionLayoutManager {
+	getFlatIndex(sectionIndex: number, itemIndex: number): number;
+	getSectionItemIndex(flatIndex: number): {
+		sectionIndex: number
+		itemIndex: number
+		isHeader: boolean
+		isFooter: boolean
+	};
+	getSectionLayout(sectionKey: string): SectionLayoutInfo | null;
+	getSectionAtOffset(offset: number): SectionLayoutInfo | null;
+	getAllSectionLayouts(): SectionLayoutInfo[];
+	setSectionCollapsed(sectionKey: string, collapsed: boolean): void;
+	isSectionCollapsed(sectionKey: string): boolean;
+	getCollapsedSections(): Set<string>;
+	updateData(sections: Section<unknown>[], collapsedSections: Set<string>): FlattenedItem<unknown>[];
+	getLayoutPositioner(): LinearLayoutPositioner;
+}
+/**
+* Factory function to create a SectionLayoutManager.
+*/
+declare function createSectionLayoutManager(layoutCache: LayoutCache, options?: {
+	horizontal?: boolean
+	estimatedItemSize?: number
+	estimatedHeaderSize?: number
+	estimatedFooterSize?: number
+	hasSectionFooters?: boolean
+}): SectionLayoutManager;
+
+interface FlattenOptions {
+	collapsedSections?: Set<string>;
+	includeSectionFooters?: boolean;
+}
+/**
+* Flatten sections into a single array of items for virtualization.
+* Each item includes metadata about its section and position.
+*/
+declare function flattenSections<TItem>(sections: Section<TItem>[], options?: FlattenOptions): FlattenedItem<TItem>[];
+/**
+* Get the flat index for a specific section and item index.
+*/
+declare function getFlatIndex<TItem>(sections: Section<TItem>[], sectionIndex: number, itemIndex: number, collapsedSections?: Set<string>, includeSectionFooters?: boolean): number;
+/**
+* Get section and item index from a flat index.
+*/
+declare function getSectionItemFromFlatIndex<TItem>(sections: Section<TItem>[], flatIndex: number, collapsedSections?: Set<string>, includeSectionFooters?: boolean): {
+	sectionIndex: number
+	itemIndex: number
+	type: "header" | "item" | "footer"
+} | null;
+
+/**
+* Key extraction utilities for list items.
+*/
+/**
+* Default key extractor that uses index as string.
+* Note: Using indices as keys is not recommended for dynamic lists.
+*/
+declare function defaultKeyExtractor<TItem>(item: TItem, index: number): string;
+/**
+* Create a key extractor function with a custom field name.
+*/
+declare function createKeyExtractor<TItem>(field: keyof TItem): (item: TItem, index: number) => string;
+/**
+* Create a composite key from multiple fields.
+*/
+declare function createCompositeKeyExtractor<TItem>(fields: (keyof TItem)[]): (item: TItem, index: number) => string;
+/**
+* Validate that keys are unique within a list.
+* Throws an error if duplicates are found.
+*/
+declare function validateUniqueKeys<TItem>(items: TItem[], keyExtractor: (item: TItem, index: number) => string): void;
+
+/**
+* Binary search utilities for efficient offset-to-index lookups.
+*/
+/**
+* Binary search to find the index of an item with a specific value.
+* Returns -1 if not found.
+*/
+declare function binarySearch<T>(array: T[], target: number, getValue: (item: T) => number): number;
+/**
+* Binary search to find the insertion position for a value.
+* Returns the index where the value should be inserted to maintain sorted order.
+*/
+declare function binarySearchInsertPosition<T>(array: T[], target: number, getValue: (item: T) => number): number;
+
+/**
+* Default configuration values for SectionFlow
+*/
+declare const DEFAULT_ESTIMATED_ITEM_SIZE = 50;
+declare const DEFAULT_ESTIMATED_HEADER_SIZE = 40;
+declare const DEFAULT_DRAW_DISTANCE = 250;
+declare const DEFAULT_MAX_POOL_SIZE = 10;
+declare const DEFAULT_ITEM_TYPE = "default";
+declare const SECTION_HEADER_TYPE = "__section_header__";
+declare const SECTION_FOOTER_TYPE = "__section_footer__";
+
+/**
+* Internal context value for SectionFlow components.
+*/
+interface SectionFlowContextValue<TItem> {
+	sections: Section<TItem>[];
+	flattenedData: FlattenedItem<TItem>[];
+	layoutManager: SectionLayoutManager;
+	layoutCache: LayoutCache;
+	horizontal: boolean;
+	collapsedSections: Set<string>;
+	scrollOffset: number;
+	viewportWidth: number;
+	viewportHeight: number;
+	stickySectionHeadersEnabled: boolean;
+	estimatedItemSize: number;
+	drawDistance: number;
+	debug: boolean;
+	renderItem: (info: RenderItemInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionHeader?: (info: RenderSectionHeaderInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionFooter?: (info: RenderSectionFooterInfo<TItem>) => React$1.ReactElement | null;
+	onCellMeasured: (key: string, flatIndex: number, layout: LayoutRect) => void;
+	onSectionToggle?: (sectionKey: string, collapsed: boolean) => void;
+	getItemType: (flatIndex: number) => string;
+}
+/**
+* Hook to access SectionFlow context.
+* Must be used within a SectionFlowProvider.
+*/
+declare function useSectionFlowContext<TItem>(): SectionFlowContextValue<TItem>;
+interface SectionFlowProviderProps<TItem> {
+	children: React$1.ReactNode;
+	sections: Section<TItem>[];
+	flattenedData: FlattenedItem<TItem>[];
+	layoutManager: SectionLayoutManager;
+	layoutCache: LayoutCache;
+	horizontal: boolean;
+	collapsedSections: Set<string>;
+	scrollOffset: number;
+	viewportWidth: number;
+	viewportHeight: number;
+	stickySectionHeadersEnabled: boolean;
+	estimatedItemSize: number;
+	drawDistance: number;
+	debug: boolean;
+	renderItem: (info: RenderItemInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionHeader?: (info: RenderSectionHeaderInfo<TItem>) => React$1.ReactElement | null;
+	renderSectionFooter?: (info: RenderSectionFooterInfo<TItem>) => React$1.ReactElement | null;
+	onCellMeasured: (key: string, flatIndex: number, layout: LayoutRect) => void;
+	onSectionToggle?: (sectionKey: string, collapsed: boolean) => void;
+	getItemType: (flatIndex: number) => string;
+}
+/**
+* Provider component for SectionFlow context.
+*/
+declare function SectionFlowProvider<TItem>({ children, sections, flattenedData, layoutManager, layoutCache, horizontal, collapsedSections, scrollOffset, viewportWidth, viewportHeight, stickySectionHeadersEnabled, estimatedItemSize, drawDistance, debug, renderItem, renderSectionHeader, renderSectionFooter, onCellMeasured, onSectionToggle, getItemType }: SectionFlowProviderProps<TItem>): React$1.ReactElement;
+
+export { AnimatedStickyHeaderContainer, DEFAULT_DRAW_DISTANCE, DEFAULT_ESTIMATED_HEADER_SIZE, DEFAULT_ESTIMATED_ITEM_SIZE, DEFAULT_ITEM_TYPE, DEFAULT_MAX_POOL_SIZE, LinearLayoutPositioner, RecyclerCell, RecyclerContainer, SECTION_FOOTER_TYPE, SECTION_HEADER_TYPE, SectionFlow, SectionFlowProvider, SectionHeader, StickyHeaderContainer, binarySearch, binarySearchInsertPosition, createCellRecycler, createCompositeKeyExtractor, createKeyExtractor, createLayoutCache, createLayoutPositioner, createSectionLayoutManager, createViewabilityTracker, defaultKeyExtractor, flattenSections, getFlatIndex, getSectionItemFromFlatIndex, useAdaptiveDrawDistance, useCellMeasurement, useItemTypeResolver, useLayoutMeasurement, useMultipleStickyHeaders, useMultipleViewabilityConfigs, useProgressiveRender, useRecycler, useScrollHandler, useSectionFlowContext, useStickyHeader, useStickyHeaderOpacity, useViewability, validateUniqueKeys };
+export type { CellRecyclerInterface, FlattenedItem, FlattenedItemType, LayoutCache, LayoutPositioner, LayoutRect, RecyclePool, RecycledCell, RenderItemInfo, RenderSectionFooterInfo, RenderSectionHeaderInfo, ScrollToItemOptions, ScrollToSectionOptions, Section, SectionFlowProps, SectionFlowRef, SectionLayoutInfo, SectionLayoutManager, ViewToken, ViewabilityConfig, ViewabilityConfigCallbackPair, ViewabilityTracker, ViewabilityTrackerInterface };