# Timeline

Стрічка активності запису — дзвінки, нотатки, зміни статусу — з машинним часом і смисловими крапками.


Історія угоди, стрічка подій замовлення, журнал змін тікета. Компонент
відповідає за розкладку й семантику часу; що саме сталося — вирішує
споживач.


Example (app/demos/timeline/TimelineBasic.vue):

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

const events: TimelineItem[] = [
  {
    id: 1,
    title: 'Угоду виграно',
    description: 'Підписано договір на ₴420 000, термін — 12 місяців.',
    datetime: '2026-08-17T16:40:00+03:00',
    tone: 'success',
  },
  {
    id: 2,
    title: 'Надіслано комерційну пропозицію',
    description: 'Версія 3 — з урахуванням знижки за річну оплату.',
    datetime: '2026-08-14T11:05:00+03:00',
    tone: 'accent',
  },
  {
    id: 3,
    title: 'Дзвінок, 14 хвилин',
    description: 'Обговорили міграцію даних і терміни впровадження.',
    datetime: '2026-08-12T09:20:00+03:00',
    tone: 'info',
  },
  {
    id: 4,
    title: 'Ліда створено',
    datetime: '2026-08-08T18:02:00+03:00',
    tone: 'neutral',
  },
]
</script>

<template>
  <div class="w-full max-w-lg rounded-card border border-line bg-card p-5">
    <h3 class="mb-4 text-sm font-semibold text-ink">Історія угоди</h3>
    <UiTimeline :items="events" />
  </div>
</template>

```


## Час мусить бути детермінованим

Сторінки цього сайту прередеряться в Node, а гідратуються в браузері. Якщо
дозволити `Intl` узяти часовий пояс процесу, сервер надрукує одну годину,
клієнт — іншу, і Vue поскаржиться на розсинхрон гідрації **на кожній
події**. Тому `timeZone` — явний props із типовим `Europe/Kyiv`.

З тієї ж причини серед значень `dateFormat` **немає** відносного часу
(«2 години тому»): він не може збігтися між сервером і клієнтом навіть
теоретично. Якщо відносний підпис потрібен, порахуйте його на клієнті й
передайте готовим у `item.time` — він перекриває форматування `datetime`.

Поле `datetime` при цьому лишається потрібним: воно йде в атрибут
`<time datetime>`, і саме звідти машини дізнаються справжній момент.

## Конектор


Example (app/demos/timeline/TimelineCompact.vue):

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

const events: TimelineItem[] = [
  { id: 1, title: 'Статус → Оплачено', time: '16:40', tone: 'success' },
  { id: 2, title: 'Рахунок надіслано', time: '15:12', tone: 'accent' },
  { id: 3, title: 'Не вдалося списати кошти', time: '14:58', tone: 'danger' },
  { id: 4, title: 'Замовлення створено', time: '14:30', tone: 'neutral' },
]
</script>

<template>
  <div class="w-full max-w-sm rounded-card border border-line bg-card p-4">
    <!-- Власна іконка замість крапки — через слот `dot`. -->
    <UiTimeline :items="events" density="sm">
      <template #dot="{ item }">
        <span
          aria-hidden="true"
          class="mt-0.5 flex h-4 w-4 items-center justify-center rounded-full text-[9px] font-bold"
          :class="item.tone === 'danger' ? 'bg-danger-bg text-danger' : 'bg-neutral-bg text-neutral'"
        >{{ item.tone === 'danger' ? '!' : '•' }}</span>
      </template>
    </UiTimeline>
  </div>
</template>

```


Лінія між крапками малюється окремим сегментом на кожній події, крім
останньої. Одна наскрізна лінія на контейнері виглядає простіше, але
звисає нижче останньої крапки щоразу, коли остання подія коротша за
попередні — а в стрічці активності остання подія зазвичай і є найкоротшою.

Положення крапки, відступ і координата лінії беруться з однієї константи
на щільність. Розвести їх по різних місцях означає розсинхронізувати
крапку з лінією на пів пікселя при зміні `density` — і це видно.

## API

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

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

- Історія запису в CRM: що відбувалося з угодою, клієнтом, тікетом.
- Журнал змін: хто і коли змінив статус.
- Стрічка доставки замовлення.

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

- Для покрокового процесу з поточним кроком — це
  [`UiStepper`](https://ui.tatet.net/docs/components/stepper): там кроки попереду ще не сталися.
- Для сотень подій без віртуалізації: розгляньте
  [`UiVirtualList`](https://ui.tatet.net/docs/components/virtual-list) як обгортку.
- Для однорідних записів із полями, які треба сортувати — це таблиця.

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

Корінь — `<ol>` (або `<ul>` через `as`), кожна подія — `<li>`. Хронологія
за замовчуванням упорядкована, і скрінрідер оголошує «список із N
елементів» разом із номером поточного.

Крапка декоративна й має `aria-hidden`: колір несе ту саму інформацію, що
й текст поруч, і дублювати її голосом немає сенсу.

Час обгорнутий у `<time :datetime>`, тож видимий скорочений підпис не
заважає машинам прочитати повний момент.


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