@dynamic-scroll/core 1.2.1

package/dist/index.d.mts

@@ -0,0 +1,346 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 가상 스크롤에 사용되는 아이템의 기본 인터페이스.
+ * 모든 아이템은 고유한 id를 가져야 한다.
+ */
+interface VirtualScrollItem {
+    id: string;
+}
+/**
+ * 가시 영역 계산 결과.
+ * useScrollState 훅이 반환하는 값.
+ */
+interface ScrollState {
+    /** 실제 뷰포트에 보이는 첫 번째 노드 인덱스 (renderAhead 미적용) */
+    firstVisibleNode: number;
+    /** 실제 뷰포트에 보이는 마지막 노드 인덱스 (renderAhead 미적용) */
+    lastVisibleNode: number;
+    /** 렌더링할 시작 인덱스 (renderAhead 적용) */
+    startNode: number;
+    /** 렌더링할 끝 인덱스 (renderAhead 적용) */
+    endNode: number;
+    /** 렌더링할 총 노드 수 */
+    visibleNodeCount: number;
+}
+/**
+ * 외부에 노출되는 imperative API.
+ * ref를 통해 스크롤 제어를 할 수 있다.
+ */
+interface DynamicScrollHandle {
+    /** 특정 인덱스의 아이템으로 스크롤 이동 */
+    scrollToItem: (index: number, align?: ScrollAlign) => void;
+    /** 하단으로 스크롤 이동 */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    /** 특정 offset으로 스크롤 이동 */
+    scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void;
+    /** 현재 스크롤 offset 반환 */
+    getScrollOffset: () => number;
+}
+/** scrollToItem의 정렬 옵션 */
+type ScrollAlign = "start" | "center" | "end";
+/**
+ * 초기 스크롤 위치 설정.
+ * - "top": 최상단에서 시작
+ * - "bottom": 최하단에서 시작 (기본값)
+ * - { index, align? }: 특정 아이템 위치에서 시작 (예: 마지막으로 읽은 메시지)
+ */
+type InitialScrollPosition = "top" | "bottom" | {
+    index: number;
+    align?: ScrollAlign;
+};
+/**
+ * DynamicScroll 컴포넌트의 props.
+ */
+interface DynamicScrollProps<T extends VirtualScrollItem> {
+    /** 렌더링할 아이템 배열 */
+    items: T[];
+    /** 아이템 렌더링 함수 */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 (기본값: 8) */
+    overscanCount?: number;
+    /** 추정 아이템 높이. 사전 측정을 건너뛰고 이 값을 기본값으로 사용 (fallback 옵션) */
+    estimatedItemSize?: number;
+    /** 상단 도달 시 호출되는 콜백 (이전 데이터 로드) */
+    onStartReached?: () => void | Promise<void>;
+    /** 하단 도달 시 호출되는 콜백 (다음 데이터 로드) */
+    onEndReached?: () => void | Promise<void>;
+    /** 상단/하단 도달 감지 임계값 (px). 기본값: 0 */
+    threshold?: number;
+    /** 하단 고정 상태 변경 시 호출되는 콜백 */
+    onAtBottomChange?: (isAtBottom: boolean) => void;
+    /** flushSync로 스크롤 업데이트를 동기 처리할지 여부 (기본값: false) */
+    syncScrollUpdates?: boolean;
+    /** 스크롤 컨테이너에 적용할 className */
+    className?: string;
+    /** 스크롤 컨테이너에 적용할 style */
+    style?: React.CSSProperties;
+    /** 그룹 분류 함수. 아이템을 그룹핑할 키를 반환 */
+    groupBy?: (item: T) => string;
+    /** sticky 그룹 헤더 렌더링 함수. 스크롤 시 상단에 떠다니는 날짜 텍스트 등 */
+    renderGroupHeader?: (groupKey: string) => ReactNode;
+    /** 그룹 구분선 렌더링 함수. 각 그룹 첫 번째에 삽입되는 수평선. 일반 아이템처럼 높이가 측정됨 */
+    renderGroupSeparator?: (groupKey: string) => ReactNode;
+    /** 상단 로딩 중 표시할 컴포넌트 */
+    loadingComponent?: ReactNode;
+    /** 하단 로딩 중 표시할 컴포넌트 */
+    bottomLoadingComponent?: ReactNode;
+    /** 초기 스크롤 위치. 기본값: "bottom" */
+    initialScrollPosition?: InitialScrollPosition;
+    /** 새 아이템의 높이 측정이 완료되었을 때 호출되는 콜백. 리마운트 없이 scrollToItem 등을 안전하게 호출할 수 있는 시점. */
+    onMeasurementComplete?: () => void;
+    /** 초기 높이 측정 중 표시할 로딩 컴포넌트 */
+    initialLoadingComponent?: ReactNode;
+}
+/**
+ * 저수준 VirtualScroll 컴포넌트의 props.
+ * 높이 측정이 이미 완료된 상태에서 사용한다.
+ */
+interface VirtualScrollProps<T extends VirtualScrollItem> {
+    /** 렌더링할 아이템 배열 */
+    items: T[];
+    /** 아이템 렌더링 함수 */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** 각 아이템의 누적 top 위치 배열 */
+    childPositions: number[];
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+    /** 높이 맵 (ref) */
+    heightMapRef: React.RefObject<Map<string, number>>;
+    /** 높이 변경 시 호출되는 콜백 */
+    onHeightChange: (id: string, height: number) => void;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 */
+    overscanCount?: number;
+    /** 상단 도달 시 호출되는 콜백 */
+    onStartReached?: () => void | Promise<void>;
+    /** 하단 도달 시 호출되는 콜백 */
+    onEndReached?: () => void | Promise<void>;
+    /** 상단/하단 도달 감지 임계값 (px) */
+    threshold?: number;
+    /** 하단 고정 상태 변경 시 호출되는 콜백 */
+    onAtBottomChange?: (isAtBottom: boolean) => void;
+    /** flushSync로 스크롤 업데이트를 동기 처리할지 여부 */
+    syncScrollUpdates?: boolean;
+    /** 스크롤 컨테이너에 적용할 className */
+    className?: string;
+    /** 스크롤 컨테이너에 적용할 style */
+    style?: React.CSSProperties;
+    /** 백그라운드 측정 진행 중 여부 (DynamicScroll 내부용) */
+    isMeasuring?: boolean;
+    /** 그룹 정보 (GroupWrapper 렌더링용) */
+    groupInfo?: {
+        heightByGroup: Map<string, number>;
+        groupKeyByIndex: string[];
+        groupStartPositions: Map<string, number>;
+    } | null;
+    /** sticky 그룹 헤더 렌더링 함수 */
+    renderGroupHeader?: (groupKey: string) => ReactNode;
+    /** 상단 로딩 중 표시할 컴포넌트 */
+    loadingComponent?: ReactNode;
+    /** 하단 로딩 중 표시할 컴포넌트 */
+    bottomLoadingComponent?: ReactNode;
+    /** 초기 스크롤 위치. 기본값: "bottom" */
+    initialScrollPosition?: InitialScrollPosition;
+}
+
+declare const DynamicScroll: <T extends VirtualScrollItem>(props: DynamicScrollProps<T> & {
+    ref?: React.Ref<DynamicScrollHandle>;
+}) => React.ReactElement | null;
+
+declare const VirtualScroll: <T extends VirtualScrollItem>(props: VirtualScrollProps<T> & {
+    ref?: React.Ref<DynamicScrollHandle>;
+}) => React.ReactElement | null;
+
+interface MeasureProps {
+    children: React.ReactNode;
+    /** 아이템 고유 식별자 */
+    itemId: string;
+    /** absolute top 위치 (px) */
+    position: number;
+    /** 높이 변경 시 호출되는 콜백 */
+    onHeightChange: (id: string, height: number) => void;
+    /** 사전 측정된 높이 (InitialMeasure에서 측정한 값). 깜빡임 방지용 높이 잠금에 사용 */
+    knownHeight?: number;
+}
+/**
+ * 가상 스크롤 내 각 아이템을 감싸는 컴포넌트.
+ *
+ * 높이 잠금 메커니즘:
+ * 1. knownHeight가 있으면 height style로 잠금 (이미지 재로드 중 깜빡임 방지)
+ * 2. MutationObserver로 내부 DOM 변경 감지 (이미지 로드 등)
+ * 3. 변경 감지 → height style 제거 (자연 리플로우)
+ * 4. ResizeObserver로 새 높이 감지 → onHeightChange 호출
+ */
+declare function MeasureInner({ children, itemId, position, onHeightChange, knownHeight, }: MeasureProps): react_jsx_runtime.JSX.Element;
+declare const Measure: react.MemoExoticComponent<typeof MeasureInner>;
+
+interface InitialMeasureProps {
+    children: React.ReactNode;
+    itemId: string;
+    onMeasured: (id: string, height: number) => void;
+}
+/**
+ * 사전 높이 측정용 컴포넌트.
+ * visibility: hidden으로 렌더링하여 실제 높이를 측정한다.
+ * 이미지가 있으면 onload를 대기한다.
+ */
+declare function InitialMeasure({ children, itemId, onMeasured, }: InitialMeasureProps): react_jsx_runtime.JSX.Element;
+
+interface StickyGroupHeaderProps {
+    /** 현재 표시할 그룹 키 */
+    groupKey: string;
+    /** 그룹 헤더 렌더링 함수 */
+    renderGroupHeader: (groupKey: string) => ReactNode;
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+    /** 해당 그룹 아래 모든 그룹의 누적 높이 */
+    cumulativeHeight: number;
+    /** 상단 오프셋 (px) */
+    topOffset?: number;
+}
+/**
+ * Sticky Group Header 컴포넌트.
+ *
+ * 가상 스크롤에서 CSS position:sticky가 동작하지 않는 문제를 해결한다.
+ * (absolute positioned 아이템들과 sticky는 호환되지 않음)
+ *
+ * 구현 방식:
+ * - position: sticky + top: 0으로 고정
+ * - height를 totalHeight - cumulativeHeight로 제한하여
+ *   해당 그룹 영역이 끝나면 자연스럽게 밀려 올라가는 push-up 효과 구현
+ * - z-index로 아이템들 위에 표시
+ */
+declare function StickyGroupHeader({ groupKey, renderGroupHeader, totalHeight, cumulativeHeight, topOffset, }: StickyGroupHeaderProps): react_jsx_runtime.JSX.Element;
+
+interface UseScrollStateParams {
+    /** 현재 스크롤 위치 */
+    scrollTop: number;
+    /** 전체 아이템 수 */
+    itemCount: number;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 (기본값: 8) */
+    overscanCount?: number;
+    /** 뷰포트 높이 */
+    viewportHeight: number;
+    /** 각 아이템의 누적 top 위치 배열 */
+    childPositions: number[];
+}
+/**
+ * scrollTop과 childPositions를 기반으로 가시 영역의 노드 범위를 계산하는 훅.
+ *
+ * - generateStartNodeIndex: 이진탐색 O(log n)으로 시작 노드 계산
+ * - generateEndNodeIndex: 이진탐색 O(log n)으로 끝 노드 계산
+ * - overscanCount만큼 전후로 버퍼를 추가하여 스크롤 시 빈 영역 방지
+ */
+declare function useScrollState({ scrollTop, itemCount, overscanCount, viewportHeight, childPositions, }: UseScrollStateParams): ScrollState;
+
+interface UsePositionsParams<T extends VirtualScrollItem> {
+    /** 아이템 배열 */
+    items: T[];
+    /** 높이 맵 ref (useHeightMap에서 제공) */
+    heightMapRef: React.RefObject<Map<string, number>>;
+    /** heightMap 변경 시 재계산 트리거용 버전 (useHeightMap에서 제공) */
+    version: number;
+    /** 추정 아이템 높이 (미측정 아이템의 fallback) */
+    estimatedItemSize?: number;
+}
+interface UsePositionsReturn {
+    /** 각 아이템의 누적 top 위치 배열. positions[i] = i번째 아이템의 top. positions[length] = totalHeight */
+    childPositions: number[];
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+}
+/**
+ * heightMapRef + version을 기반으로 childPositions를 계산하는 훅.
+ *
+ * - heightMapRef는 useHeightMap에서 관리하는 ref를 그대로 받는다
+ * - version이 변경될 때마다 useMemo가 재계산된다
+ * - 미측정 아이템은 estimatedItemSize 또는 0으로 처리
+ */
+declare function usePositions<T extends VirtualScrollItem>({ items, heightMapRef, version, estimatedItemSize, }: UsePositionsParams<T>): UsePositionsReturn;
+
+interface UseHeightMapParams<T extends VirtualScrollItem> {
+    items: T[];
+    estimatedItemSize?: number;
+}
+interface UseHeightMapReturn {
+    heightMapRef: React.RefObject<Map<string, number>>;
+    isAllMeasured: boolean;
+    unmeasuredIds: string[];
+    onItemMeasured: (id: string, height: number) => void;
+    onHeightChange: (id: string, height: number) => void;
+    version: number;
+}
+/**
+ * 아이템 높이 맵을 관리하는 훅.
+ *
+ * - heightMap은 useRef<Map>으로 저장
+ * - InitialMeasure: pendingIds Set으로 미측정 추적, 0이 되면 1번 리렌더
+ * - ResizeObserver: rAF 배치
+ */
+declare function useHeightMap<T extends VirtualScrollItem>({ items, estimatedItemSize, }: UseHeightMapParams<T>): UseHeightMapReturn;
+
+interface GroupInfo {
+    /** 그룹 키 → 해당 그룹의 전체 높이 */
+    heightByGroup: Map<string, number>;
+    /** 그룹 키 → 해당 그룹 아래 모든 그룹의 누적 높이 (sticky 헤더 height 제한용) */
+    cumulativeHeightByGroup: Map<string, number>;
+    /** 인덱스 → 해당 아이템이 속한 그룹 키 */
+    groupKeyByIndex: string[];
+}
+/**
+ * 그룹별 높이 정보를 계산하는 훅.
+ *
+ * sticky group header의 height 제한에 사용된다.
+ * cumulativeHeightByGroup은 최신 그룹부터 0, 이전 그룹일수록 아래 그룹들의 누적 높이.
+ *
+ * @param items - 아이템 배열
+ * @param groupBy - 아이템을 그룹핑할 키를 반환하는 함수
+ * @param heightMapRef - 높이 맵 ref
+ * @param version - heightMap 변경 트리거용 버전
+ */
+declare function useGroupPositions<T extends VirtualScrollItem>(items: T[], groupBy: ((item: T) => string) | undefined, heightMapRef: React.RefObject<Map<string, number>>, version: number): GroupInfo | null;
+
+/**
+ * 이진 탐색으로 scrollTop에 해당하는 첫 번째 가시 노드 인덱스를 찾는다.
+ *
+ * nodePositions[i]는 i번째 아이템의 top 위치 (누적합 배열).
+ * 노드의 중앙점(nodeCenter)과 scrollTop을 비교하여
+ * 현재 뷰포트 최상단에 위치한 노드를 O(log n)으로 찾는다.
+ *
+ * @param scrollTop - 현재 스크롤 위치
+ * @param nodePositions - 누적 위치 배열 (길이: itemCount + 1)
+ * @param itemCount - 전체 아이템 수
+ * @returns 첫 번째 가시 노드의 인덱스
+ */
+declare function generateStartNodeIndex(scrollTop: number, nodePositions: number[], itemCount: number): number;
+/**
+ * 이진 탐색으로 뷰포트를 넘어서는 마지막 가시 노드 인덱스를 찾는다.
+ *
+ * 기존 구현은 선형 탐색 O(k)였으나, 이진 탐색 O(log n)으로 개선.
+ * startNodeIndex의 다음 노드 위치를 기준으로 viewportHeight를 더한
+ * 경계값을 초과하는 첫 번째 노드를 찾는다.
+ *
+ * @param nodePositions - 누적 위치 배열
+ * @param startNodeIndex - 첫 번째 가시 노드 인덱스 (renderAhead 미적용)
+ * @param itemCount - 전체 아이템 수
+ * @param viewportHeight - 뷰포트 높이
+ * @returns 마지막 가시 노드의 인덱스
+ */
+declare function generateEndNodeIndex(nodePositions: number[], startNodeIndex: number, itemCount: number, viewportHeight: number): number;
+/**
+ * 이진 탐색으로 타겟 아이템을 뷰포트 중앙에 배치하기 위한 시작 노드 인덱스를 찾는다.
+ *
+ * 타겟 아이템의 중심이 뷰포트 중앙(viewportHeight / 2)에 오도록 하는
+ * scrollTop 위치의 첫 번째 가시 노드를 찾는다.
+ *
+ * @param nodePositions - 누적 위치 배열
+ * @param targetRowHeight - 타겟 아이템의 높이
+ * @param targetRowIndex - 타겟 아이템의 인덱스
+ * @param viewportHeight - 뷰포트 높이
+ * @returns 시작 노드 인덱스
+ */
+declare function generateCenteredStartNodeIndex(nodePositions: number[], targetRowHeight: number, targetRowIndex: number, viewportHeight: number): number;
+
+export { DynamicScroll, type DynamicScrollHandle, type DynamicScrollProps, InitialMeasure, type InitialScrollPosition, Measure, type ScrollAlign, type ScrollState, StickyGroupHeader, VirtualScroll, type VirtualScrollItem, type VirtualScrollProps, generateCenteredStartNodeIndex, generateEndNodeIndex, generateStartNodeIndex, useGroupPositions, useHeightMap, usePositions, useScrollState };

package/dist/index.d.ts

@@ -0,0 +1,346 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * 가상 스크롤에 사용되는 아이템의 기본 인터페이스.
+ * 모든 아이템은 고유한 id를 가져야 한다.
+ */
+interface VirtualScrollItem {
+    id: string;
+}
+/**
+ * 가시 영역 계산 결과.
+ * useScrollState 훅이 반환하는 값.
+ */
+interface ScrollState {
+    /** 실제 뷰포트에 보이는 첫 번째 노드 인덱스 (renderAhead 미적용) */
+    firstVisibleNode: number;
+    /** 실제 뷰포트에 보이는 마지막 노드 인덱스 (renderAhead 미적용) */
+    lastVisibleNode: number;
+    /** 렌더링할 시작 인덱스 (renderAhead 적용) */
+    startNode: number;
+    /** 렌더링할 끝 인덱스 (renderAhead 적용) */
+    endNode: number;
+    /** 렌더링할 총 노드 수 */
+    visibleNodeCount: number;
+}
+/**
+ * 외부에 노출되는 imperative API.
+ * ref를 통해 스크롤 제어를 할 수 있다.
+ */
+interface DynamicScrollHandle {
+    /** 특정 인덱스의 아이템으로 스크롤 이동 */
+    scrollToItem: (index: number, align?: ScrollAlign) => void;
+    /** 하단으로 스크롤 이동 */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    /** 특정 offset으로 스크롤 이동 */
+    scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void;
+    /** 현재 스크롤 offset 반환 */
+    getScrollOffset: () => number;
+}
+/** scrollToItem의 정렬 옵션 */
+type ScrollAlign = "start" | "center" | "end";
+/**
+ * 초기 스크롤 위치 설정.
+ * - "top": 최상단에서 시작
+ * - "bottom": 최하단에서 시작 (기본값)
+ * - { index, align? }: 특정 아이템 위치에서 시작 (예: 마지막으로 읽은 메시지)
+ */
+type InitialScrollPosition = "top" | "bottom" | {
+    index: number;
+    align?: ScrollAlign;
+};
+/**
+ * DynamicScroll 컴포넌트의 props.
+ */
+interface DynamicScrollProps<T extends VirtualScrollItem> {
+    /** 렌더링할 아이템 배열 */
+    items: T[];
+    /** 아이템 렌더링 함수 */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 (기본값: 8) */
+    overscanCount?: number;
+    /** 추정 아이템 높이. 사전 측정을 건너뛰고 이 값을 기본값으로 사용 (fallback 옵션) */
+    estimatedItemSize?: number;
+    /** 상단 도달 시 호출되는 콜백 (이전 데이터 로드) */
+    onStartReached?: () => void | Promise<void>;
+    /** 하단 도달 시 호출되는 콜백 (다음 데이터 로드) */
+    onEndReached?: () => void | Promise<void>;
+    /** 상단/하단 도달 감지 임계값 (px). 기본값: 0 */
+    threshold?: number;
+    /** 하단 고정 상태 변경 시 호출되는 콜백 */
+    onAtBottomChange?: (isAtBottom: boolean) => void;
+    /** flushSync로 스크롤 업데이트를 동기 처리할지 여부 (기본값: false) */
+    syncScrollUpdates?: boolean;
+    /** 스크롤 컨테이너에 적용할 className */
+    className?: string;
+    /** 스크롤 컨테이너에 적용할 style */
+    style?: React.CSSProperties;
+    /** 그룹 분류 함수. 아이템을 그룹핑할 키를 반환 */
+    groupBy?: (item: T) => string;
+    /** sticky 그룹 헤더 렌더링 함수. 스크롤 시 상단에 떠다니는 날짜 텍스트 등 */
+    renderGroupHeader?: (groupKey: string) => ReactNode;
+    /** 그룹 구분선 렌더링 함수. 각 그룹 첫 번째에 삽입되는 수평선. 일반 아이템처럼 높이가 측정됨 */
+    renderGroupSeparator?: (groupKey: string) => ReactNode;
+    /** 상단 로딩 중 표시할 컴포넌트 */
+    loadingComponent?: ReactNode;
+    /** 하단 로딩 중 표시할 컴포넌트 */
+    bottomLoadingComponent?: ReactNode;
+    /** 초기 스크롤 위치. 기본값: "bottom" */
+    initialScrollPosition?: InitialScrollPosition;
+    /** 새 아이템의 높이 측정이 완료되었을 때 호출되는 콜백. 리마운트 없이 scrollToItem 등을 안전하게 호출할 수 있는 시점. */
+    onMeasurementComplete?: () => void;
+    /** 초기 높이 측정 중 표시할 로딩 컴포넌트 */
+    initialLoadingComponent?: ReactNode;
+}
+/**
+ * 저수준 VirtualScroll 컴포넌트의 props.
+ * 높이 측정이 이미 완료된 상태에서 사용한다.
+ */
+interface VirtualScrollProps<T extends VirtualScrollItem> {
+    /** 렌더링할 아이템 배열 */
+    items: T[];
+    /** 아이템 렌더링 함수 */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** 각 아이템의 누적 top 위치 배열 */
+    childPositions: number[];
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+    /** 높이 맵 (ref) */
+    heightMapRef: React.RefObject<Map<string, number>>;
+    /** 높이 변경 시 호출되는 콜백 */
+    onHeightChange: (id: string, height: number) => void;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 */
+    overscanCount?: number;
+    /** 상단 도달 시 호출되는 콜백 */
+    onStartReached?: () => void | Promise<void>;
+    /** 하단 도달 시 호출되는 콜백 */
+    onEndReached?: () => void | Promise<void>;
+    /** 상단/하단 도달 감지 임계값 (px) */
+    threshold?: number;
+    /** 하단 고정 상태 변경 시 호출되는 콜백 */
+    onAtBottomChange?: (isAtBottom: boolean) => void;
+    /** flushSync로 스크롤 업데이트를 동기 처리할지 여부 */
+    syncScrollUpdates?: boolean;
+    /** 스크롤 컨테이너에 적용할 className */
+    className?: string;
+    /** 스크롤 컨테이너에 적용할 style */
+    style?: React.CSSProperties;
+    /** 백그라운드 측정 진행 중 여부 (DynamicScroll 내부용) */
+    isMeasuring?: boolean;
+    /** 그룹 정보 (GroupWrapper 렌더링용) */
+    groupInfo?: {
+        heightByGroup: Map<string, number>;
+        groupKeyByIndex: string[];
+        groupStartPositions: Map<string, number>;
+    } | null;
+    /** sticky 그룹 헤더 렌더링 함수 */
+    renderGroupHeader?: (groupKey: string) => ReactNode;
+    /** 상단 로딩 중 표시할 컴포넌트 */
+    loadingComponent?: ReactNode;
+    /** 하단 로딩 중 표시할 컴포넌트 */
+    bottomLoadingComponent?: ReactNode;
+    /** 초기 스크롤 위치. 기본값: "bottom" */
+    initialScrollPosition?: InitialScrollPosition;
+}
+
+declare const DynamicScroll: <T extends VirtualScrollItem>(props: DynamicScrollProps<T> & {
+    ref?: React.Ref<DynamicScrollHandle>;
+}) => React.ReactElement | null;
+
+declare const VirtualScroll: <T extends VirtualScrollItem>(props: VirtualScrollProps<T> & {
+    ref?: React.Ref<DynamicScrollHandle>;
+}) => React.ReactElement | null;
+
+interface MeasureProps {
+    children: React.ReactNode;
+    /** 아이템 고유 식별자 */
+    itemId: string;
+    /** absolute top 위치 (px) */
+    position: number;
+    /** 높이 변경 시 호출되는 콜백 */
+    onHeightChange: (id: string, height: number) => void;
+    /** 사전 측정된 높이 (InitialMeasure에서 측정한 값). 깜빡임 방지용 높이 잠금에 사용 */
+    knownHeight?: number;
+}
+/**
+ * 가상 스크롤 내 각 아이템을 감싸는 컴포넌트.
+ *
+ * 높이 잠금 메커니즘:
+ * 1. knownHeight가 있으면 height style로 잠금 (이미지 재로드 중 깜빡임 방지)
+ * 2. MutationObserver로 내부 DOM 변경 감지 (이미지 로드 등)
+ * 3. 변경 감지 → height style 제거 (자연 리플로우)
+ * 4. ResizeObserver로 새 높이 감지 → onHeightChange 호출
+ */
+declare function MeasureInner({ children, itemId, position, onHeightChange, knownHeight, }: MeasureProps): react_jsx_runtime.JSX.Element;
+declare const Measure: react.MemoExoticComponent<typeof MeasureInner>;
+
+interface InitialMeasureProps {
+    children: React.ReactNode;
+    itemId: string;
+    onMeasured: (id: string, height: number) => void;
+}
+/**
+ * 사전 높이 측정용 컴포넌트.
+ * visibility: hidden으로 렌더링하여 실제 높이를 측정한다.
+ * 이미지가 있으면 onload를 대기한다.
+ */
+declare function InitialMeasure({ children, itemId, onMeasured, }: InitialMeasureProps): react_jsx_runtime.JSX.Element;
+
+interface StickyGroupHeaderProps {
+    /** 현재 표시할 그룹 키 */
+    groupKey: string;
+    /** 그룹 헤더 렌더링 함수 */
+    renderGroupHeader: (groupKey: string) => ReactNode;
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+    /** 해당 그룹 아래 모든 그룹의 누적 높이 */
+    cumulativeHeight: number;
+    /** 상단 오프셋 (px) */
+    topOffset?: number;
+}
+/**
+ * Sticky Group Header 컴포넌트.
+ *
+ * 가상 스크롤에서 CSS position:sticky가 동작하지 않는 문제를 해결한다.
+ * (absolute positioned 아이템들과 sticky는 호환되지 않음)
+ *
+ * 구현 방식:
+ * - position: sticky + top: 0으로 고정
+ * - height를 totalHeight - cumulativeHeight로 제한하여
+ *   해당 그룹 영역이 끝나면 자연스럽게 밀려 올라가는 push-up 효과 구현
+ * - z-index로 아이템들 위에 표시
+ */
+declare function StickyGroupHeader({ groupKey, renderGroupHeader, totalHeight, cumulativeHeight, topOffset, }: StickyGroupHeaderProps): react_jsx_runtime.JSX.Element;
+
+interface UseScrollStateParams {
+    /** 현재 스크롤 위치 */
+    scrollTop: number;
+    /** 전체 아이템 수 */
+    itemCount: number;
+    /** 뷰포트 전후로 추가 렌더링할 아이템 수 (기본값: 8) */
+    overscanCount?: number;
+    /** 뷰포트 높이 */
+    viewportHeight: number;
+    /** 각 아이템의 누적 top 위치 배열 */
+    childPositions: number[];
+}
+/**
+ * scrollTop과 childPositions를 기반으로 가시 영역의 노드 범위를 계산하는 훅.
+ *
+ * - generateStartNodeIndex: 이진탐색 O(log n)으로 시작 노드 계산
+ * - generateEndNodeIndex: 이진탐색 O(log n)으로 끝 노드 계산
+ * - overscanCount만큼 전후로 버퍼를 추가하여 스크롤 시 빈 영역 방지
+ */
+declare function useScrollState({ scrollTop, itemCount, overscanCount, viewportHeight, childPositions, }: UseScrollStateParams): ScrollState;
+
+interface UsePositionsParams<T extends VirtualScrollItem> {
+    /** 아이템 배열 */
+    items: T[];
+    /** 높이 맵 ref (useHeightMap에서 제공) */
+    heightMapRef: React.RefObject<Map<string, number>>;
+    /** heightMap 변경 시 재계산 트리거용 버전 (useHeightMap에서 제공) */
+    version: number;
+    /** 추정 아이템 높이 (미측정 아이템의 fallback) */
+    estimatedItemSize?: number;
+}
+interface UsePositionsReturn {
+    /** 각 아이템의 누적 top 위치 배열. positions[i] = i번째 아이템의 top. positions[length] = totalHeight */
+    childPositions: number[];
+    /** 전체 컨텐츠 높이 */
+    totalHeight: number;
+}
+/**
+ * heightMapRef + version을 기반으로 childPositions를 계산하는 훅.
+ *
+ * - heightMapRef는 useHeightMap에서 관리하는 ref를 그대로 받는다
+ * - version이 변경될 때마다 useMemo가 재계산된다
+ * - 미측정 아이템은 estimatedItemSize 또는 0으로 처리
+ */
+declare function usePositions<T extends VirtualScrollItem>({ items, heightMapRef, version, estimatedItemSize, }: UsePositionsParams<T>): UsePositionsReturn;
+
+interface UseHeightMapParams<T extends VirtualScrollItem> {
+    items: T[];
+    estimatedItemSize?: number;
+}
+interface UseHeightMapReturn {
+    heightMapRef: React.RefObject<Map<string, number>>;
+    isAllMeasured: boolean;
+    unmeasuredIds: string[];
+    onItemMeasured: (id: string, height: number) => void;
+    onHeightChange: (id: string, height: number) => void;
+    version: number;
+}
+/**
+ * 아이템 높이 맵을 관리하는 훅.
+ *
+ * - heightMap은 useRef<Map>으로 저장
+ * - InitialMeasure: pendingIds Set으로 미측정 추적, 0이 되면 1번 리렌더
+ * - ResizeObserver: rAF 배치
+ */
+declare function useHeightMap<T extends VirtualScrollItem>({ items, estimatedItemSize, }: UseHeightMapParams<T>): UseHeightMapReturn;
+
+interface GroupInfo {
+    /** 그룹 키 → 해당 그룹의 전체 높이 */
+    heightByGroup: Map<string, number>;
+    /** 그룹 키 → 해당 그룹 아래 모든 그룹의 누적 높이 (sticky 헤더 height 제한용) */
+    cumulativeHeightByGroup: Map<string, number>;
+    /** 인덱스 → 해당 아이템이 속한 그룹 키 */
+    groupKeyByIndex: string[];
+}
+/**
+ * 그룹별 높이 정보를 계산하는 훅.
+ *
+ * sticky group header의 height 제한에 사용된다.
+ * cumulativeHeightByGroup은 최신 그룹부터 0, 이전 그룹일수록 아래 그룹들의 누적 높이.
+ *
+ * @param items - 아이템 배열
+ * @param groupBy - 아이템을 그룹핑할 키를 반환하는 함수
+ * @param heightMapRef - 높이 맵 ref
+ * @param version - heightMap 변경 트리거용 버전
+ */
+declare function useGroupPositions<T extends VirtualScrollItem>(items: T[], groupBy: ((item: T) => string) | undefined, heightMapRef: React.RefObject<Map<string, number>>, version: number): GroupInfo | null;
+
+/**
+ * 이진 탐색으로 scrollTop에 해당하는 첫 번째 가시 노드 인덱스를 찾는다.
+ *
+ * nodePositions[i]는 i번째 아이템의 top 위치 (누적합 배열).
+ * 노드의 중앙점(nodeCenter)과 scrollTop을 비교하여
+ * 현재 뷰포트 최상단에 위치한 노드를 O(log n)으로 찾는다.
+ *
+ * @param scrollTop - 현재 스크롤 위치
+ * @param nodePositions - 누적 위치 배열 (길이: itemCount + 1)
+ * @param itemCount - 전체 아이템 수
+ * @returns 첫 번째 가시 노드의 인덱스
+ */
+declare function generateStartNodeIndex(scrollTop: number, nodePositions: number[], itemCount: number): number;
+/**
+ * 이진 탐색으로 뷰포트를 넘어서는 마지막 가시 노드 인덱스를 찾는다.
+ *
+ * 기존 구현은 선형 탐색 O(k)였으나, 이진 탐색 O(log n)으로 개선.
+ * startNodeIndex의 다음 노드 위치를 기준으로 viewportHeight를 더한
+ * 경계값을 초과하는 첫 번째 노드를 찾는다.
+ *
+ * @param nodePositions - 누적 위치 배열
+ * @param startNodeIndex - 첫 번째 가시 노드 인덱스 (renderAhead 미적용)
+ * @param itemCount - 전체 아이템 수
+ * @param viewportHeight - 뷰포트 높이
+ * @returns 마지막 가시 노드의 인덱스
+ */
+declare function generateEndNodeIndex(nodePositions: number[], startNodeIndex: number, itemCount: number, viewportHeight: number): number;
+/**
+ * 이진 탐색으로 타겟 아이템을 뷰포트 중앙에 배치하기 위한 시작 노드 인덱스를 찾는다.
+ *
+ * 타겟 아이템의 중심이 뷰포트 중앙(viewportHeight / 2)에 오도록 하는
+ * scrollTop 위치의 첫 번째 가시 노드를 찾는다.
+ *
+ * @param nodePositions - 누적 위치 배열
+ * @param targetRowHeight - 타겟 아이템의 높이
+ * @param targetRowIndex - 타겟 아이템의 인덱스
+ * @param viewportHeight - 뷰포트 높이
+ * @returns 시작 노드 인덱스
+ */
+declare function generateCenteredStartNodeIndex(nodePositions: number[], targetRowHeight: number, targetRowIndex: number, viewportHeight: number): number;
+
+export { DynamicScroll, type DynamicScrollHandle, type DynamicScrollProps, InitialMeasure, type InitialScrollPosition, Measure, type ScrollAlign, type ScrollState, StickyGroupHeader, VirtualScroll, type VirtualScrollItem, type VirtualScrollProps, generateCenteredStartNodeIndex, generateEndNodeIndex, generateStartNodeIndex, useGroupPositions, useHeightMap, usePositions, useScrollState };