frontend-svelte/src/shared/ui/VirtualList/VirtualList.svelte

<!--
    Component: VirtualList

    High-performance virtualized list for large datasets with:
    - Virtual scrolling (only renders visible items + overscan)
    - Keyboard navigation (ArrowUp/Down, Home, End)
    - Fixed or dynamic item heights
    - ARIA listbox/option pattern with single tab stop
-->
<script lang="ts" generics="T">
import { createVirtualizer } from '$shared/lib';
import { cn } from '$shared/shadcn/utils/shadcn-utils';
import type { Snippet } from 'svelte';

interface Props {
    /**
     * Array of items to render in the virtual list.
     *
     * @template T - The type of items in the list
     */
    items: T[];
    /**
     * Total number of items (including not-yet-loaded items for pagination).
     * If not provided, defaults to items.length.
     *
     * Use this when implementing pagination to ensure the scrollbar
     * reflects the total count of items, not just the loaded ones.
     *
     * @example
     * ```ts
     * // Pagination scenario: 1920 total fonts, but only 50 loaded
     * <VirtualList items={loadedFonts} total={1920}>
     * ```
     */
    total?: number;
    /**
     * Height for each item, either as a fixed number
     * or a function that returns height per index.
     * @default 80
     */
    itemHeight?: number | ((index: number) => number);
    /**
     * Optional overscan value for the virtual list.
     * @default 5
     */
    overscan?: number;
    /**
     * Optional CSS class string for styling the container
     * (follows shadcn convention for className prop)
     */
    class?: string;
    /**
     * An optional callback that will be called for each new set of loaded items
     * @param items - Loaded items
     */
    onVisibleItemsChange?: (items: T[]) => void;
    /**
     * An optional callback that will be called when user scrolls near the end of the list.
     * Useful for triggering auto-pagination.
     *
     * The callback receives the index of the last visible item. You can use this
     * to determine if you should load more data.
     *
     * @example
     * ```ts
     * onNearBottom={(lastVisibleIndex) => {
     *     const itemsRemaining = total - lastVisibleIndex;
     *     if (itemsRemaining < 5 && hasMore && !isFetching) {
     *         loadMore();
     *     }
     * }}
     * ```
     */
    onNearBottom?: (lastVisibleIndex: number) => void;
    /**
     * Snippet for rendering individual list items.
     *
     * The snippet receives an object containing:
     * - `item`: The item from the items array (type T)
     * - `index`: The current item's index in the array
     *
     * This pattern provides type safety and flexibility for
     * rendering different item types without prop drilling.
     *
     * @template T - The type of items in the list
     */
    children: Snippet<
        [{ item: T; index: number; isVisible: boolean; proximity: number }]
    >;
}

let {
    items,
    total = items.length,
    itemHeight = 80,
    overscan = 5,
    class: className,
    onVisibleItemsChange,
    onNearBottom,
    children,
}: Props = $props();

const virtualizer = createVirtualizer(() => ({
    count: items.length,
    data: items,
    estimateSize: typeof itemHeight === 'function' ? itemHeight : () => itemHeight,
    overscan,
}));

$effect(() => {
    const visibleItems = virtualizer.items.map(item => items[item.index]);
    onVisibleItemsChange?.(visibleItems);

    // Trigger onNearBottom when user scrolls near the end of loaded items (within 5 items)
    if (virtualizer.items.length > 0 && onNearBottom) {
        const lastVisibleItem = virtualizer.items[virtualizer.items.length - 1];
        // Compare against loaded items length, not total
        const itemsRemaining = items.length - lastVisibleItem.index;

        if (itemsRemaining <= 5) {
            onNearBottom(lastVisibleItem.index);
        }
    }
});
</script>

<div
    use:virtualizer.container
    class={cn(
        'relative overflow-auto rounded-md bg-background',
        'h-150 w-full',
        'scroll-smooth',
        className,
    )}
    onfocusin={(e => {
        // Prevent the browser from jumping the scroll when an inner element gets focus
        e.preventDefault();
    })}
>
    <div
        style:height="{virtualizer.totalSize}px"
        class="w-full pointer-events-none"
    >
    </div>

    {#each virtualizer.items as item (item.key)}
        <div
            use:virtualizer.measureElement
            data-index={item.index}
            class="absolute top-0 left-0 w-full"
            style:transform="translateY({item.start}px)"
        >
            {#if item.index < items.length}
                {@render children({
    item: items[item.index],
    index: item.index,
    isVisible: item.isVisible,
    proximity: item.proximity,
})}
            {/if}
        </div>
    {/each}
</div>