# VirtualList

Віртуалізований список із фіксованою висотою рядка — рендерить лише видиме вікно діапазону з overscan-запасом.


## Приклад


Example (app/demos/virtual-list/VirtualListBasic.vue):

```vue
<script setup lang="ts">
import UiVirtualList from '~/components/ui/UiVirtualList.vue'

interface Row extends Record<string, unknown> {
  id: number
  label: string
  value: number
}

// 10 000 рядків. Значення детерміновані: (i * 7919) % 1000, а не Math.random()
// — інакше прередер і клієнт показали б різні числа.
const items: Row[] = Array.from({ length: 10_000 }, (_, i) => ({
  id: i,
  label: `Рядок №${i + 1}`,
  value: (i * 7919) % 1000,
}))
</script>

<template>
  <UiVirtualList :items="items" :item-height="36" height="16rem">
    <template #item="{ item, index }">
      <div class="flex h-full items-center justify-between gap-3 border-b border-line px-3">
        <span class="min-w-0 truncate text-sm">{{ item.label }}</span>
        <span class="shrink-0 text-xs tabular-nums text-muted">#{{ index }} · {{ item.value }}</span>
      </div>
    </template>
  </UiVirtualList>
</template>
```


Всередині сцени — 10 000 рядків; у DOM їх менше кількох десятків: списком
керує позиція скролу, а не розмір масиву.

## API

[Props, events, slots, exposed API (JSON)](https://ui.tatet.net/api/component-meta/UiVirtualList)

## Слоти

Єдиний слот — `item`, і він обов'язковий: без нього списку нема чим
малювати. Слот отримує `{ item, index }` (`index` — абсолютний номер у
`items`, а не позиція у вікні) і рендерить вміст ОДНОГО рядка. Висоту
рядка задає сам компонент (`itemHeight`), тож у слоті не можна покладатися
на `min-h` чи `py-` — рядок має вкладатися у відведені пікселі:

```vue
<UiVirtualList ref="list" :items="items" :item-height="36">
  <template #item="{ item, index }">
    <div class="flex items-center px-3">{{ index }}. {{ item.label }}</div>
  </template>
</UiVirtualList>
```

Програмна прокрутка — `list.value.scrollToIndex(index)`: рядок опиняється
посередині вікна, позиція клаймиться в межі полотна. При різкому
скороченні `items` стара позиція скролу, що вилізла за нове полотно,
скидається на початок — інакше вікно діапазону рахувалося б із «висячого»
scrollTop і список показував би порожнє місце.

Висоту вікна список перечитує щоразу, коли змінюється сам контейнер, — через
`ResizeObserver`, а не лише за подією `resize` вікна. Новий `height`,
панель [`UiResizablePanels`](https://ui.tatet.net/docs/components/resizable-panels), згорнутий
сайдбар чи монтаж у схованій вкладці раніше лишали низ списку порожнім,
доки користувач не прокрутить. Тому `height="100%"` у панелі, що
змінює висоту, — робочий сценарій.

Тип рядка — звичайний `interface`: обмеження генерика `Record<string, any>`
приймає його без `extends Record<…>`.

## Коли використовувати

Для довгих однорідних списків — логів, стрічок платіжок, результатів
пошуку, — де рендер всіх рядків означає тисячі зайвих вузлів DOM. Разом з
UiPagination: пагінація зменшує обсяг даних, віртуалізація — кількість
відрендерених вузлів.

## Коли НЕ використовувати

**Контракт фіксованої висоти.** `itemHeight` — не налаштування, а
передумова: уся арифметика віртуалізації (позиція діапазону, зміщення
рядків, загальна висота полотна) обчислюється множенням на це число.
Змінна висота рядків ламає розрахунок — останні екрани списку або не
показуються, або показуються з дірками. Рядки різної висоти — це не
«складніший випадок», а інший компонент.

Для коротких списків до кількох сотень рядків: звичайний `v-for` дешевший
за вимірювання скролу, а браузер сам впорається з кількома сотнями вузлів.

## Доступність

Прокрутка контейнера доступна з клавіатури як звичайна зона скролу
(`overflow-y-auto`). Рядки — абсолютні прямокутники з координатами
`top = index * itemHeight`, тож порядок у DOM відповідає порядку на
екрані; ключ рядків береться з `keyField`, щоб фокус і стан рядка не
загубилися під час перемальовування вікна.

[Source files, dependencies and ZIP](https://ui.tatet.net/registry/components/virtual-list.json)
