# TreeTable

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


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

## Приклад


Example (app/demos/tree-table/TreeTableCatalog.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiButton from '~/components/ui/UiButton.vue'
import UiTreeTable, { type TreeTableHeader } from '~/components/ui/UiTreeTable.vue'

interface Category extends Record<string, unknown> {
  id: number
  name: string
  alias: string
  items: number
  createdAt: string
  updatedAt: string
  children?: Category[]
}

const GROUPS = [
  'Техніка та електроніка',
  'Товари для дому',
  'Одяг і взуття',
  'Дитячі товари',
  'Спорт і відпочинок',
  'Автотовари',
  'Краса та здоров’я',
  'Зоотовари',
  'Сад і город',
  'Книги та канцтовари',
  'Будматеріали',
  'Продукти',
]

const KINDS = ['Аксесуари', 'Комплектуючі', 'Витратні матеріали', 'Набори']
const FACETS = ['преміум', 'базові', 'уцінка']

/*
 * Дані детерміновані: (i * 7919) % n замість Math.random() і жодного
 * new Date(). Демо прередериться, і випадкові числа дали б різні
 * значення на сервері й у браузері — гідратація з розбіжностями.
 */
function stamp(seed: number): string {
  const day = 1 + ((seed * 7919) % 28)
  const month = 1 + ((seed * 13) % 12)
  return `${String(day).padStart(2, '0')}.${String(month).padStart(2, '0')}.2026`
}

let nextId = 1

function makeNode(name: string, depth: number, children?: Category[]): Category {
  const id = nextId++
  return {
    id,
    name,
    alias: `${name.slice(0, 12).toLowerCase().replace(/[^a-zа-яіїєґ]+/gi, '-')}-${id}`,
    items: children?.length ? 0 : 3 + ((id * 7919) % 240),
    createdAt: stamp(id),
    updatedAt: stamp(id + 17),
    children,
  }
}

const catalog: Category[] = GROUPS.map((group) =>
  makeNode(
    group,
    0,
    KINDS.map((kind) =>
      makeNode(
        `${kind}`,
        1,
        FACETS.map((facet) =>
          makeNode(
            `${kind}, ${facet}`,
            2,
            [makeNode(`${facet} — вітрина`, 3), makeNode(`${facet} — склад`, 3)],
          ),
        ),
      ),
    ),
  ),
)

// Два верхні рівні відкриті одразу: так на екрані більше двохсот рядків,
// поріг віртуалізації (100) перейдено, і демо показує саме її.
const openByDefault: number[] = []
for (const group of catalog) {
  openByDefault.push(group.id)
  for (const kind of group.children ?? []) openByDefault.push(kind.id)
}

const headers: TreeTableHeader[] = [
  { value: 'name', text: 'Структура', width: 320, sortable: true },
  { value: 'alias', text: 'Alias', width: 200, sortable: true },
  { value: 'items', text: 'Товарів', width: 100, align: 'right', sortable: true },
  { value: 'createdAt', text: 'Створено', width: 120, sortable: true },
  { value: 'updatedAt', text: 'Оновлено', width: 120, sortable: true, flex: true },
]

const expanded = ref<(string | number)[]>(openByDefault)
const selected = ref<(string | number)[]>([])
const sort = ref<{ by: string; dir: 'asc' | 'desc' } | null>(null)
/*
 * Тип посилання описаний структурно, а не через InstanceType: для
 * генеричних SFC (`generic="T"`) `typeof Component` — це функція, а не
 * конструктор, і InstanceType до неї не застосовується.
 */
const tree = ref<{
  expandAll: () => void
  collapseAll: () => void
  scrollToKey: (key: string | number) => boolean
} | null>(null)
</script>

<template>
  <div class="w-full min-w-0 space-y-3">
    <div class="flex flex-wrap items-center gap-2">
      <UiButton size="sm" variant="outline" @click="tree?.expandAll()">Розгорнути все</UiButton>
      <UiButton size="sm" variant="outline" @click="tree?.collapseAll()">Згорнути все</UiButton>
      <UiButton size="sm" variant="ghost" @click="tree?.scrollToKey(catalog.at(-1)!.id)">
        До останньої групи
      </UiButton>
      <p class="ml-auto text-xs text-muted">
        {{ catalog.length }} груп · 492 вузли · видимих рядків: {{ expanded.length ? '204+' : '12' }}
      </p>
    </div>

    <UiTreeTable
      ref="tree"
      v-model:expanded="expanded"
      v-model:selected="selected"
      v-model:sort="sort"
      :headers="headers"
      :items="catalog"
      table-id="demo-catalog"
      selectable
      sticky-tree-column
      mobile-cards
      :card-height="150"
      max-height="24rem"
      aria-label="Каталог категорій"
    >
      <template #icon="{ hasChildren, expanded: open }">
        <!--
          Три стани — відкрита тека, закрита тека, аркуш. Контури взяті з
          Lucide без змін: власноруч домальована «відкрита» тека з
          прямокутника й трикутника читається як зламана іконка, бо в неї
          немає перспективи передньої стінки.
        -->
        <svg
          class="h-4 w-4"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          stroke-width="1.5"
          stroke-linecap="round"
          stroke-linejoin="round"
          aria-hidden="true"
        >
          <path
            v-if="hasChildren && open"
            d="M6 14l1.45-2.9A2 2 0 0 1 9.24 10H20a2 2 0 0 1 1.94 2.5l-1.55 6a2 2 0 0 1-1.94 1.5H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h3.9a2 2 0 0 1 1.69.9l.81 1.2a2 2 0 0 0 1.67.9H18a2 2 0 0 1 2 2v2"
          />
          <path
            v-else-if="hasChildren"
            d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"
          />
          <template v-else>
            <path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z" />
            <path d="M14 2v4a2 2 0 0 0 2 2h4" />
          </template>
        </svg>
      </template>

      <template #cell-items="{ item }">
        <span class="tabular-nums" :class="(item.items as number) ? 'text-ink' : 'text-muted'">
          {{ (item.items as number) || '—' }}
        </span>
      </template>

      <template #selection-actions="{ clear }">
        <UiButton size="sm" variant="ghost" @click="clear">Скинути</UiButton>
      </template>
    </UiTreeTable>
  </div>
</template>

```


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

## Ліниве завантаження


Example (app/demos/tree-table/TreeTableLazy.vue):

```vue
<script setup lang="ts">
import { ref } from 'vue'
import UiTreeTable, { type TreeTableHeader } from '~/components/ui/UiTreeTable.vue'

interface Folder extends Record<string, unknown> {
  id: number
  name: string
  alias: string
  childsCount: number
  items: number
  children?: Folder[]
}

/*
 * Ліниве дерево: у вузла є childsCount, але немає children. Саме за цим
 * компонент і відрізняє «діти ще їдуть» від «гілка порожня»: undefined —
 * перше, [] — друге.
 */
function folder(id: number, name: string, childsCount: number): Folder {
  return {
    id,
    name,
    alias: `folder-${id}`,
    childsCount,
    items: childsCount ? 0 : 5 + ((id * 7919) % 90),
  }
}

const roots = ref<Folder[]>([
  folder(1, 'Довідка', 3),
  folder(2, 'Формати реклами', 2),
  folder(3, 'Аналітика', 0),
])

const loadingIds = ref<(string | number)[]>([])
const expanded = ref<(string | number)[]>([])

function findNode(nodes: Folder[], id: string | number): Folder | null {
  for (const node of nodes) {
    if (node.id === id) return node
    const hit = node.children ? findNode(node.children, id) : null
    if (hit) return hit
  }
  return null
}

function onExpand({ id, loaded }: { id: string | number; loaded: boolean }) {
  // loaded каже, що діти вже приїжджали: другий запит не потрібен.
  if (loaded) return
  loadingIds.value = [...loadingIds.value, id]

  // Затримка імітує мережу. Значення дітей детерміновані — від id батька.
  setTimeout(() => {
    const parent = findNode(roots.value, id)
    if (parent) {
      parent.children = Array.from({ length: parent.childsCount }, (_, i) => {
        const childId = Number(id) * 100 + i + 1
        return folder(childId, `${parent.name} — розділ ${i + 1}`, i === 0 ? 2 : 0)
      })
      roots.value = [...roots.value]
    }
    loadingIds.value = loadingIds.value.filter((value) => value !== id)
  }, 600)
}

const headers: TreeTableHeader[] = [
  { value: 'name', text: 'Структура', width: 280, sortable: true },
  { value: 'alias', text: 'Alias', width: 140 },
  { value: 'items', text: 'Товарів', width: 100, align: 'right', flex: true },
]
</script>

<template>
  <UiTreeTable
    v-model:expanded="expanded"
    :headers="headers"
    :items="roots"
    :loading-ids="loadingIds"
    :has-children="(item) => (item.childsCount as number) > 0"
    max-height="18rem"
    aria-label="Ліниве дерево розділів"
    @expand="onExpand"
  />
</template>

```


`expandAll()` (і «Розгорнути всі» в меню налаштувань) для лінивих гілок,
відкритих уперше, віддає `expand` з `loaded: false` — так само, як клік.
Інакше вони лишалися б відкритими й порожніми без жодного сигналу.

`undefined` і `[]` у полі дітей — різні стани. Перше означає «діти ще
їдуть»: рядок лишається `aria-busy`, замість шеврона крутиться індикатор
із `loadingIds`. Друге означає «гілка справді порожня». Компонент розрізняє
їх сам, режим перемикати не треба.

## Дані з файлу


Example (app/demos/tree-table/TreeTableJson.vue):

```vue
<script setup lang="ts">
import { computed, ref, watch } from 'vue'
import UiAlert from '~/components/ui/UiAlert.vue'
import UiButton from '~/components/ui/UiButton.vue'
import UiChip from '~/components/ui/UiChip.vue'
import UiCheckbox from '~/components/ui/UiCheckbox.vue'
import UiFileUpload from '~/components/ui/UiFileUpload.vue'
import UiInput from '~/components/ui/UiInput.vue'
import UiToggleGroup from '~/components/ui/UiToggleGroup.vue'
import UiTextarea from '~/components/ui/UiTextarea.vue'
import UiTreeTable, { type TreeTableHeader } from '~/components/ui/UiTreeTable.vue'
import { labelClass } from '~/utils/uiFieldStyles'
import { filterTree } from '~/utils/treeTable'

/** Формат вивантаження дерева категорій: вузол + плоский `data`. */
interface ShopNode extends Record<string, unknown> {
  id: number
  parent: number
  name: string
  children?: ShopNode[]
  data?: {
    active?: number
    categoryTitle?: string | null
    categoryId?: number
    childsCount?: number
    itemsCount?: number
    itemsXmlCount?: number
  }
}

function node(
  id: number,
  parent: number,
  name: string,
  data: Partial<NonNullable<ShopNode['data']>>,
  children: ShopNode[] = [],
): ShopNode {
  return {
    id,
    parent,
    name,
    children,
    data: { active: 1, categoryTitle: null, categoryId: 0, childsCount: children.length, itemsCount: 0, itemsXmlCount: 0, ...data },
  }
}

/** Зразок у тому ж форматі, що й вивантаження — щоб сторінка не була порожньою. */
const SAMPLE: ShopNode[] = [
  node(1265685, 0, 'it off', { active: 0 }, [
    node(4171161, 1265685, 'Захист екрану хлам', { active: 0, itemsCount: 26 }),
    node(4233695, 1265685, 'Технічні та загальні товари', { itemsCount: 1 }),
  ]),
  node(6054982, 0, 'Відеоспостереження', {
    categoryTitle: 'IP-камери',
    categoryId: 156790,
    itemsCount: 14,
    itemsXmlCount: 14,
  }),
  node(4825198, 0, 'Катя', {}, [
    node(4825199, 4825198, 'Дитяча термобілизна', {
      categoryTitle: 'Дитяча термобілизна',
      categoryId: 1658277,
      itemsCount: 13,
      itemsXmlCount: 13,
    }),
  ]),
  node(4396136, 0, 'Ігрові маніпулятори й аксесуари до консолей', {
    categoryTitle: 'Ігрові маніпулятори й аксесуари до консолей',
    categoryId: 80173,
    itemsCount: 8,
    itemsXmlCount: 8,
  }),
]

const items = ref<ShopNode[]>(SAMPLE)
const source = ref('зразок')
const error = ref('')
const pasted = ref('')
// Гілки зразка відкриті одразу: інакше демо показує лише корені, і те,
// заради чого воно існує — вкладеність, — доводиться шукати кліком.
const expanded = ref<(string | number)[]>([1265685, 4825198])

/* ---------------------------------------------------------------- */
/*  Пошук і фільтри                                                 */
/* ---------------------------------------------------------------- */

const query = ref('')
const status = ref<string | number>('all')
const onlyLinked = ref(false)

const STATUS_OPTIONS = [
  { value: 'all', label: 'Усі' },
  { value: 'active', label: 'Активні' },
  { value: 'off', label: 'Вимкнені' },
]

/** Предикат по ОДНОМУ вузлу. Предків збігу підставляє filterTree. */
function matchesNode(item: ShopNode): boolean {
  if (status.value === 'active' && !item.data?.active) return false
  if (status.value === 'off' && item.data?.active) return false
  if (onlyLinked.value && !item.data?.categoryId) return false

  const needle = query.value.trim().toLowerCase()
  if (!needle) return true
  const title = item.data?.categoryTitle ?? ''
  return item.name.toLowerCase().includes(needle) || title.toLowerCase().includes(needle)
}

const filtering = computed(
  () => query.value.trim() !== '' || status.value !== 'all' || onlyLinked.value,
)

const view = computed(() => {
  // Без активного фільтра дерево віддається ЯК Є — жодних копій вузлів,
  // тож і зайвих перемальовувань немає.
  if (!filtering.value) return { items: items.value, matched: [], expand: [] }
  return filterTree(items.value, {
    getId: (item) => item.id,
    getChildren: (item) => item.children,
    withChildren: (item, children) => ({ ...item, children }),
    matches: matchesNode,
  })
})

/*
 * Під фільтром гілки розгортаються самі: знайдений вузол лежить на
 * третьому рівні, і без цього результат виглядав би як порожній список
 * кількох тек. Розгортання користувача при цьому не губиться — воно
 * відкладається і повертається, коли фільтр знімають.
 */
let savedExpanded: (string | number)[] | null = null

watch([filtering, () => view.value.expand], ([on, expand]) => {
  if (on) {
    if (savedExpanded === null) savedExpanded = [...expanded.value]
    expanded.value = expand as (string | number)[]
  } else if (savedExpanded !== null) {
    expanded.value = savedExpanded
    savedExpanded = null
  }
})

/**
 * Українська множина: 1 вузол, 2 вузли, 5 вузлів.
 *
 * Голе `N вузлів` читається як помилка перекладу рівно там, де число
 * найчастіше й дорівнює одиниці — у результаті пошуку.
 */
function plural(count: number, one: string, few: string, many: string) {
  const mod10 = count % 10
  const mod100 = count % 100
  if (mod10 === 1 && mod100 !== 11) return one
  if (mod10 >= 2 && mod10 <= 4 && (mod100 < 12 || mod100 > 14)) return few
  return many
}

function resetFilters() {
  query.value = ''
  status.value = 'all'
  onlyLinked.value = false
}
const tree = ref<{ expandAll: () => void; collapseAll: () => void } | null>(null)

/**
 * Поля лежать не на вузлі, а у вкладеному `data`. Саме для цього в
 * компонента є `getValue`: перекладати дані під колонки не треба.
 *
 * Ключі колонок навмисно БЕЗ крапок: `cell-data.active` у шаблоні
 * розібрався б як слот `cell-data` з модифікатором `active`.
 */
function getValue(item: ShopNode, key: string): unknown {
  if (key === 'name') return item.name
  return item.data?.[key as keyof NonNullable<ShopNode['data']>]
}

const headers: TreeTableHeader[] = [
  { value: 'name', text: 'Структура', width: 300, sortable: true },
  { value: 'categoryTitle', text: 'Категорія', width: 190, sortable: true },
  { value: 'itemsCount', text: 'Товарів', width: 90, align: 'right', sortable: true },
  { value: 'itemsXmlCount', text: 'У XML', width: 80, align: 'right', sortable: true },
  { value: 'active', text: 'Статус', width: 110, sortable: true, flex: true },
]

const stats = computed(() => {
  let count = 0
  let depth = 0
  let leaves = 0
  const walk = (nodes: ShopNode[], level: number) => {
    for (const item of nodes) {
      count += 1
      depth = Math.max(depth, level)
      const kids = item.children ?? []
      if (kids.length) walk(kids, level + 1)
      else leaves += 1
    }
  }
  walk(view.value.items, 1)
  return { count, depth, leaves }
})

/*
 * Дублікати id — не косметика: рядки ключуються саме id, тож два вузли з
 * одним id ламають і :key, і виділення, і фокус. У вивантаженні назви
 * повторюються часто, id — ніколи, тож перевіряти варто саме їх.
 */
const duplicateIds = computed(() => {
  const seen = new Set<number>()
  const dupes = new Set<number>()
  const walk = (nodes: ShopNode[]) => {
    for (const item of nodes) {
      if (seen.has(item.id)) dupes.add(item.id)
      else seen.add(item.id)
      walk(item.children ?? [])
    }
  }
  walk(items.value)
  return [...dupes]
})

function applyRaw(raw: string, from: string) {
  let parsed: unknown
  try {
    parsed = JSON.parse(raw)
  } catch (cause) {
    error.value = `Некоректний JSON — ${(cause as Error).message}`
    return
  }
  if (!Array.isArray(parsed)) {
    error.value = 'На верхньому рівні очікується масив вузлів.'
    return
  }
  const broken = parsed.find(
    (item) => !item || typeof item !== 'object' || (item as ShopNode).id === undefined,
  )
  if (broken) {
    error.value = 'У кожного вузла має бути поле id.'
    return
  }
  error.value = ''
  items.value = parsed as ShopNode[]
  source.value = from
  expanded.value = []
  savedExpanded = null
  resetFilters()
}

function onSelect(files: File[]) {
  const file = files[0]
  if (!file) return
  const reader = new FileReader()
  reader.onerror = () => {
    error.value = 'Не вдалося прочитати файл.'
  }
  reader.onload = () => applyRaw(String(reader.result ?? ''), file.name)
  reader.readAsText(file)
}
</script>

<template>
  <div class="w-full min-w-0 space-y-3">
    <UiFileUpload
      accept=".json,application/json"
      label="Перетягніть JSON сюди"
      hint="Масив вузлів: id, parent, name, children[], data{}. Файл нікуди не надсилається — читається у браузері."
      @select="onSelect"
      @error="error = $event"
    />

    <details class="rounded-card border border-line bg-card px-3 py-2">
      <summary class="cursor-pointer text-sm text-muted">Або вставити JSON текстом</summary>
      <div class="mt-2 space-y-2">
        <UiTextarea v-model="pasted" :rows="4" size="sm" placeholder="[{ &quot;id&quot;: 1, &quot;parent&quot;: 0, &quot;name&quot;: &quot;…&quot;, &quot;children&quot;: [] }]" />
        <UiButton size="sm" :disabled="!pasted.trim()" @click="applyRaw(pasted, 'вставлений текст')">
          Показати
        </UiButton>
      </div>
    </details>

    <UiAlert v-if="error" tone="danger" title="Не вдалося прочитати дані">{{ error }}</UiAlert>

    <UiAlert v-if="duplicateIds.length" tone="warning" title="Повторювані id">
      {{ duplicateIds.length }} вузлів мають неунікальний id (напр. {{ duplicateIds[0] }}). Рядки
      ключуються за id, тож виділення й фокус працюватимуть неправильно.
    </UiAlert>

    <!--
      Панель фільтрів — НАД таблицею, поза контейнером прокрутки: усередині
      нього вона поїхала б горизонтально разом із колонками й зникла б
      рівно тоді, коли до неї треба повернутись.

      Три речі тримають рядок рівним, і кожна з них — не косметика:

      1. Розміри підібрані так, щоб КОНТРОЛИ збігалися по висоті. Шкали
         не паралельні: у перемикача до висоти сегмента додається ще
         `p-1` доріжки, тож `sm` дає 26.25 + 7.5 = 33.75px. Це рівно
         висота поля `md` і кнопки `md` — саме ця трійка й стоїть тут.
      2. Лейбл має або кожна колонка, або жодна. Коли він був лише в
         пошуку, саме пошук і виглядав з'їхалим; підпис перемикача взято
         з того самого `labelClass`, що й у поля.
      3. Кнопка скидання не з'являється й не зникає, а вимикається:
         `v-if` смикав ширину рядка щоразу, коли фільтр ставав активним.
    -->
    <div class="flex flex-wrap items-end gap-3 rounded-card border border-line bg-card p-3">
      <div class="min-w-56 flex-1">
        <UiInput
          v-model="query"
          type="search"
          size="md"
          label="Пошук"
          placeholder="Назва або категорія"
        />
      </div>

      <div>
        <span :class="labelClass">Статус</span>
        <UiToggleGroup v-model="status" :options="STATUS_OPTIONS" size="sm" aria-label="Статус" />
      </div>

      <!-- Обгортка тієї ж висоти, що й поле: інакше прапорець без
           підпису зверху висне вище за решту рядка. -->
      <div class="flex h-12 items-center md:h-9">
        <UiCheckbox v-model="onlyLinked">
          <span class="text-sm whitespace-nowrap">Лише прив’язані</span>
        </UiCheckbox>
      </div>

      <UiButton
        size="md"
        variant="outline"
        class="ml-auto"
        :disabled="!filtering"
        @click="resetFilters"
      >
        Скинути
      </UiButton>
    </div>

    <div class="flex flex-wrap items-center gap-2">
      <UiButton size="sm" variant="outline" @click="tree?.expandAll()">Розгорнути все</UiButton>
      <UiButton size="sm" variant="outline" @click="tree?.collapseAll()">Згорнути все</UiButton>
      <p class="ml-auto text-xs text-muted">
        <span v-if="filtering">Знайдено {{ view.matched.length }} · показано</span>
        <span v-else>Джерело — {{ source }} ·</span>
        {{ stats.count }} {{ plural(stats.count, 'вузол', 'вузли', 'вузлів') }} · глибина
        {{ stats.depth }} · {{ stats.leaves }}
        {{ plural(stats.leaves, 'листок', 'листки', 'листків') }}
      </p>
    </div>

    <UiTreeTable
      ref="tree"
      v-model:expanded="expanded"
      :headers="headers"
      :items="view.items"
      :get-value="getValue"
      table-id="demo-json"
      max-height="22rem"
      :empty-text="filtering ? 'Нічого не знайдено' : 'Оберіть файл, щоб побачити дерево'"
      aria-label="Дерево з файлу"
    >
      <template #cell-categoryTitle="{ item }">
        <span :class="item.data?.categoryTitle ? 'text-ink' : 'text-muted'">
          {{ item.data?.categoryTitle ?? 'не прив’язано' }}
        </span>
      </template>

      <template #cell-active="{ item }">
        <UiChip :tone="item.data?.active ? 'success' : 'neutral'" size="sm">
          {{ item.data?.active ? 'Активна' : 'Вимкнена' }}
        </UiChip>
      </template>
    </UiTreeTable>
  </div>
</template>

```


Перетягніть у зону власне вивантаження — масив вузлів
`{ id, parent, name, children[], data{} }` — і воно відрендериться як є.
Файл нікуди не надсилається: його читає `FileReader` у браузері.

Поля тут лежать не на вузлі, а у вкладеному `data`, і саме для цього
існує `getValue`: перекладати дані під форму колонок не треба, достатньо
описати, звідки брати значення. Ключі колонок при цьому — без крапок,
інакше `#cell-data.active` розбереться як слот `cell-data` з
модифікатором `active`.

Над таблицею — пошук і фільтри. Плоский `filter` тут не працює
принципово: вузол, що збігся, без предків втрачає місце в ієрархії, а
без предків його ще й не видно. Тому `filterTree` лишає вузол, якщо
збігся він сам АБО хтось у його піддереві, і окремо повертає список
гілок, які треба розгорнути. Розгортання користувача при цьому не
губиться — воно повертається, коли фільтр знімають.

Діти фільтруються навіть у вузла, що збігся сам: інакше «лише активні»
показувало б вимкнених дітей активної теки, тобто рівно те, що просили
сховати.

Демо заразом перевіряє те, що зазвичай помічають надто пізно: чи
унікальні `id`. Рядки ключуються саме ними, тож у вивантаженні з
повторами ламаються `:key`, виділення й фокус — а назви, на відміну від
id, повторюються суцільно.

## Пагінація


Example (app/demos/tree-table/TreeTablePaged.vue):

```vue
<script setup lang="ts">
import { computed, ref, watch } from 'vue'
import UiPagination from '~/components/ui/UiPagination.vue'
import UiTreeTable, { type TreeTableHeader } from '~/components/ui/UiTreeTable.vue'

interface Section extends Record<string, unknown> {
  id: number
  name: string
  owner: string
  updatedAt: string
  children?: Section[]
}

const OWNERS = ['Олена', 'Тарас', 'Ірина', 'Богдан', 'Марта']

// Детерміновано: (i * 7919) % n замість Math.random() і без new Date() —
// інакше прередер і клієнт показали б різні значення.
function stamp(seed: number) {
  const day = 1 + ((seed * 7919) % 28)
  const month = 1 + ((seed * 13) % 12)
  return `${String(day).padStart(2, '0')}.${String(month).padStart(2, '0')}.2026`
}

const sections: Section[] = Array.from({ length: 40 }, (_, r) => {
  const id = r + 1
  return {
    id,
    name: `Розділ ${id}`,
    owner: OWNERS[id % OWNERS.length]!,
    updatedAt: stamp(id),
    children: Array.from({ length: 3 }, (_, c) => {
      const childId = id * 100 + c + 1
      return {
        id: childId,
        name: `Розділ ${id} — підрозділ ${c + 1}`,
        owner: OWNERS[childId % OWNERS.length]!,
        updatedAt: stamp(childId),
        children: Array.from({ length: 2 }, (_, g) => {
          const leafId = childId * 10 + g + 1
          return {
            id: leafId,
            name: `Розділ ${id}.${c + 1} — сторінка ${g + 1}`,
            owner: OWNERS[leafId % OWNERS.length]!,
            updatedAt: stamp(leafId),
          }
        }),
      }
    }),
  }
})

const headers: TreeTableHeader[] = [
  { value: 'name', text: 'Структура', width: 300, sortable: true },
  { value: 'owner', text: 'Відповідальний', width: 150, sortable: true },
  { value: 'updatedAt', text: 'Оновлено', width: 120, sortable: true, flex: true },
]

const page = ref(1)
const pageSize = ref(10)
const expanded = ref<(string | number)[]>([1])

/*
 * Сторінками йдуть КОРЕНІ, а не рядки.
 *
 * Різати плоский список видимих рядків не можна: дитина опинилась би на
 * наступній сторінці без свого батька, тобто без єдиного, що пояснює її
 * місце. Тому сторінка — це N коренів РАЗОМ з їхніми піддеревами, і
 * загальна кількість рахується теж по коренях.
 */
const totalPages = computed(() => Math.max(1, Math.ceil(sections.length / pageSize.value)))

const pageRoots = computed(() => {
  const start = (page.value - 1) * pageSize.value
  return sections.slice(start, start + pageSize.value)
})

// Зміна розміру сторінки майже завжди вибиває поточну сторінку за межі
// діапазону — повертаємось на першу, як і будь-який список.
watch(pageSize, () => {
  page.value = 1
})
</script>

<template>
  <div class="w-full min-w-0 space-y-3">
    <UiTreeTable
      v-model:expanded="expanded"
      :headers="headers"
      :items="pageRoots"
      max-height="20rem"
      aria-label="Розділи посторінково"
    />

    <UiPagination
      v-model:page="page"
      v-model:page-size="pageSize"
      :total-pages="totalPages"
      :total-items="sections.length"
      :page-size-options="[5, 10, 20]"
    />
  </div>
</template>

```


Сторінками йдуть **корені**, а не рядки. Різати плоский список видимих
рядків не можна: дитина опинилась би на наступній сторінці без свого
батька — тобто без єдиного, що пояснює її місце. Тому сторінка — це N
коренів РАЗОМ з їхніми піддеревами, і загальна кількість рахується теж
по коренях.

Оновлення вже показаних даних (`loading` при непорожньому `items`) не
замінює дерево скелетоном — розгорнуті гілки лишаються на місці під
напівпрозорим оверлеєм. Скелетон з'являється лише на першому завантаженні.

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

## API

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

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

Ієрархічні дані, у яких на кожен вузол є ще й колонки: дерево сторінок
сайту з alias і датами, каталог категорій із лічильниками товарів, дерево
рахунків із сумами. Тобто всюди, де `Tree` не вистачає через колонки, а
`Table` — через вкладеність.

Великі дерева. Поріг `virtualizeFrom` (типово 100 видимих рядків) вмикає
вікно автоматично, тож той самий компонент обслуговує і десять рядків, і
десять тисяч.

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

**Плоскі дані — `Table`.** Він уміє те саме з колонками, але без контракту
фіксованої висоти, тож рядок там росте за вмістом.

**Дерево без колонок — `Tree`.** Легший, без арифметики вікна й без
`<colgroup>`.

**Однорідний список без ієрархії — `VirtualList`.**

**Рядки змінної висоти.** `rowHeight` — це передумова, а не налаштування:
уся арифметика вікна множить його на індекс. Рядок мусить вкладатися у
задану висоту (`truncate`, фіксована кількість рядків тексту). Це інший
компонент, а не важчий випадок цього.

**Пошук по сторінці і друк.** Ctrl+F і принтер бачать лише вікно —
властивість будь-якої віртуалізації. Для друку й експорту вимикайте її:
`:virtualize-from="Infinity"` разом із `max-height="none"`.

**Перетягування вузлів.** Зміна батька — це мутація даних, а не подання;
компонент її не робить і робити не буде.

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

`role="treegrid"` з `aria-rowcount` на таблиці; на рядку — `aria-level`,
`aria-posinset`, `aria-setsize`, `aria-rowindex`, `aria-expanded` (у
листків його немає взагалі), `aria-selected`, `aria-busy`. Колонка
ієрархії — `rowheader`, решта — `gridcell`.

Roving tabindex: Tab бере лише активний рядок. ↑↓ рухають, → розгортає й
далі спускається, ← згортає й далі підіймається до батька, `*` розкриває
всіх сусідів рівня, Home/End і PageUp/PageDown ходять по списку, Space
перемикає вибір гілки. Літери шукають набором: «ан» переводить фокус на
наступний рядок, чий підпис починається з «ан»; буфер живе 600 мс.

При `selectable` Ctrl/Cmd+A обирає все дерево, Escape знімає вибір (і не
спливає далі, поки вибір є — модалка з таблицею від нього не закриється).

Коли активний рядок зникає — згорнули предка кліком по шеврону чи
«Згорнути все» — Tab-зупинка переходить до найближчого видимого предка,
а не на початок списку.

Клавіші з вкладених контролів рядок не перехоплює: Enter на кнопці в
слоті комірки натискає кнопку, стрілки в полі вводу рухають каретку.
Прапорець виділення — виняток: стрілки з нього рухають рядки.

Рядок за межами вікна фізично відсутній у DOM, тож перед `focus()`
компонент зсуває вікно і лише потім фокусує — з `preventScroll`, інакше
браузер додає власну прокрутку і виходить подвійний стрибок.

Шеврон — `span` під `aria-hidden`, а не кнопка. Кнопка на кожному рядку
поставила б у Tab-порядок між двома сусідніми рядками стільки кнопок,
скільки рядків у вікні; доступна афорданс розгортання — це `aria-expanded`
плюс ← і →.

Прапорець рядка при `selectable` лишається справжнім `input`, тож Tab
обходить прапорці ВІДРЕНДЕРЕНИХ рядків. Клавіатурному користувачу вони не
потрібні: Space на рядку робить те саме.

## Каскадне виділення

Вибір гілки бере її саму й усіх нащадків; батько показує `indeterminate`,
поки обрано частину. Масив `selected` містить **і батьків, і дітей** —
інакше масова дія «видалити обране» мовчки пропускала б теку, яку
користувач і клікнув. Потрібні лише листки — відфільтруйте на своєму боці.

У лінивому режимі це має третій наслідок: діти, що приїхали під уже
позначену теку, автоматично доливаються в набір, тож `selected` **росте**
з розгортанням. Якщо ваш API приймає id теки й сам розбирається з
піддеревом, приберіть нащадків перед відправкою.

Прапорець у шапці рахується по ВСЬОМУ дереву, а не по видимих рядках. У
плоскій таблиці «сторінка» дорівнює видимому; у дереві прив'язка до
видимого зробила б сенс галочки залежним від того, які теки випадково
відкриті.

## Сортування

Сортуються тільки сусіди в межах одного батька — ієрархія не сплющується
ніколи, бо обхід сортує рівно той масив, у який зараз спускається.

При `serverSort` компонент лише повідомляє намір через `update:sort`.
Сервер при цьому зобов'язаний сортувати **сусідів усередині батька**:
поверне плоский глобально відсортований список — ієрархія загине, і
компонент цього не помітить, бо діти лишаться дітьми, просто не тими.

## Деталі реалізації

Віртуалізація зроблена розпірними рядками, а не абсолютним
позиціюванням: абсолютний `tr` вибиває рядок із табличного боксу, і
`<colgroup>` перестає керувати ширинами. Тому таблиця справжня, а над і
під вікном стоять два порожні `tr` порахованої висоти.

Таблиця — `border-separate` з нульовим `border-spacing`, а роздільник
рядків — псевдоелемент. Будь-який `border` на `tr` чи `td` увійшов би у
висоту рядка, а вікно множить її на індекс: один зайвий піксель
накопичується і зсуває хвіст списку.

Щільність задає ЧИСЛО висоти рядка, а не паддінг: висота мусить бути
відома до рендеру й однакова на сервері та клієнті. Адаптивної пари
`{ base, md }` тому немає — сервер не знає ширини вікна.

`mobileCards` тримає обидві розкладки в DOM, а вибирає між ними CSS.
Прихований контейнер спорожнюється **виміром**: `ResizeObserver` віддає
під `display: none` нульовий бокс. `matchMedia` тут неможливий — він
правдивий лише після монтування, і гілка по брейкпойнту розійшлася б із
прередереним HTML на все тіло таблиці.

Панель налаштувань колонок — спільний компонент із `UiTable`
(`app/components/ui/table/ColumnSettings.vue`), як і арифметика ширин,
порівняння значень і зведення збереженої розкладки
(`app/utils/tableColumns.ts` — імпортуйте звідти напряму, `treeTable.ts`
цих функцій не ре-експортує). Дві копії тієї самої панелі розходяться
мовчки: у дереві кнопки порядку встигли отримати зону дотику й
SVG-стрілки, а в плоскій таблиці лишались текстові «↑↓» без зони.
Керування гілками приходить у панель слотом — це єдине, чого в плоскій
таблиці немає.

Кнопка, що відкриває панель, теж спільна і стоїть там само, де в
[`UiTable`](https://ui.tatet.net/docs/components/table#налаштування-колонок): у правому куті
шапки, без власного рядка, з появою на наведенні. Шапка дерева липка
завжди, тож і кут тримається верху безумовно. З `mobileCards` нижче `md`
кнопка переходить у рядок над картками — кута там немає.

З `tableId` розкладка зберігається під ключем
`tree_table_settings_${tableId}`, а відкриті гілки — окремо, під
`tree_table_expanded_${tableId}`. Ключі різні, бо різний час життя:
розкладка вмирає від `settingsVersion`, розгортання — разом із даними.
Один payload означав би, що зміна дефолтної ширини колонки заразом
закриває всім користувачам усі теки.

Збережене застосовується лише після монтування, тож на прередереній
сторінці видно короткий проблиск дефолтної розкладки. Тут він помітніший,
ніж у `Table`: збережена щільність міняє висоту рядка, а з нею — розпірки
й діапазон вікна.


## Event descriptions

- `update:expanded`: Набір відкритих гілок. Використовуйте через `v-model:expanded`.
- `update:selected`: Ключі обраних вузлів, включно з батьками. Використовуйте через `v-model:selected`.
- `update:sort`: Нове сортування або `null` на третьому кліку. Використовуйте через `v-model:sort`.
- `update:headers`: Розкладка колонок після ресайзу чи меню налаштувань.
- `expand`: Гілку відкрито. `loaded` каже, чи діти вже завантажені.
- `collapse`: Гілку закрито.
- `rowClick`: Активація рядка кліком або Enter при `rowClickable`.


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