# Timeline

> Menampilkan apa saja yang terjadi pada sebuah data, terbaru di atas.

Timeline menampilkan riwayat sebuah data, terbaru di atas, misalnya perubahan status clearance atau aktivitas pada kontrak.

## Kapan dipakai

- Pakai untuk riwayat: perubahan status, persetujuan, unggahan, komentar.
- Taruh kejadian terbaru di atas.
- Untuk kejadian yang baru terjadi, tampilkan waktu relatif ("2 jam lalu") dan taruh tanggal lengkapnya di `dateTime` dan `title`; kejadian yang lebih lama menampilkan tanggalnya.
- Untuk langkah yang masih akan dijalani, pakai [Stepper](https://design.sosialoka.tech/id/components/stepper/).

_Pratinjau langsung versi React dan Vue: https://design.sosialoka.tech/id/components/timeline/_

## Anatomi

1. Kejadian terbaru
2. Titik kejadian
3. Garis penghubung
4. Judul dan waktu

Daftar berurut. Setiap kejadian punya titik, garis ke kejadian berikutnya, waktu, judul, dan deskripsi opsional.

| Bagian | Gaya |
| --- | --- |
| Titik | 10px (`size-2.5`), `rounded-full`. Bawaannya `primary`; `success`, `warning`, `destructive`, atau `muted-foreground` sesuai status. |
| Garis | 1px (`w-px`), `border` |
| Waktu | `text-xs`, `muted-foreground`, di elemen `<time>` |
| Judul | `text-sm`, `font-medium` |
| Deskripsi | `text-sm`, `muted-foreground` |

## Props

| React | Vue | Flutter | Tipe | Bawaan | Kegunaan |
| --- | --- | --- | --- | --- | --- |
| `TimelineItem status` | `:status` | warna titik dari tema | `default` \| `success` \| `warning` \| `destructive` \| `muted` | `default` | Warna titik. |
| `TimelineTime dateTime` | `datetime` | `Text` | teks | tidak ada | Waktu kejadian yang bisa dibaca mesin. |
| `TimelineTitle`, `TimelineDescription` | sama | `Text` | teks | tidak ada | Apa yang terjadi. |

`shadcn_ui` tidak punya timeline; snippet Flutter menggambar titik dan garisnya dari tema.

## Kode

**React**
```tsx
import { Timeline, TimelineDescription, TimelineItem, TimelineTime, TimelineTitle } from "@/components/ui/timeline"

const events = [
  { status: "success", title: "Disetujui", time: "2026-11-12T14:20", label: "12 Nov 2026, 14.20", text: "Lisensi cover siap dipakai." },
  { status: "default", title: "Ditinjau", time: "2026-11-10T10:05", label: "10 Nov 2026, 10.05", text: "Tim kami memeriksa dokumenmu." },
  { status: "default", title: "Dokumen diterima", time: "2026-11-08T16:40", label: "8 Nov 2026, 16.40", text: "Surat kuasa dan master audio lengkap." },
  { status: "muted", title: "Diajukan", time: "2026-11-05T09:12", label: "5 Nov 2026, 09.12", text: "Kamu mengajukan clearance." },
] as const

export default function TimelineDemo() {
  return (
    <Timeline aria-label="Riwayat clearance Senja di Kota" className="w-full max-w-sm">
      {events.map((e) => (
        <TimelineItem key={e.title} status={e.status}>
          <TimelineTime dateTime={e.time}>{e.label}</TimelineTime>
          <TimelineTitle>{e.title}</TimelineTitle>
          <TimelineDescription>{e.text}</TimelineDescription>
        </TimelineItem>
      ))}
    </Timeline>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { Timeline, TimelineDescription, TimelineItem, TimelineTime, TimelineTitle } from "@/components/ui/timeline"

const events = [
  { status: "success", title: "Disetujui", time: "2026-11-12T14:20", label: "12 Nov 2026, 14.20", text: "Lisensi cover siap dipakai." },
  { status: "default", title: "Ditinjau", time: "2026-11-10T10:05", label: "10 Nov 2026, 10.05", text: "Tim kami memeriksa dokumenmu." },
  { status: "default", title: "Dokumen diterima", time: "2026-11-08T16:40", label: "8 Nov 2026, 16.40", text: "Surat kuasa dan master audio lengkap." },
  { status: "muted", title: "Diajukan", time: "2026-11-05T09:12", label: "5 Nov 2026, 09.12", text: "Kamu mengajukan clearance." },
] as const
</script>

<template>
  <Timeline aria-label="Riwayat clearance Senja di Kota" class="w-full max-w-sm">
    <TimelineItem v-for="e in events" :key="e.title" :status="e.status">
      <TimelineTime :datetime="e.time">
        {{ e.label }}
      </TimelineTime>
      <TimelineTitle>{{ e.title }}</TimelineTitle>
      <TimelineDescription>{{ e.text }}</TimelineDescription>
    </TimelineItem>
  </Timeline>
</template>
```

**Flutter**
```dart
// shadcn_ui has no timeline: a column of dots and lines drawn from tokens, newest event on top.
// Each event is one Semantics node, so a screen reader reads title, time and text together.
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';
import 'package:sosialoka_ui/sosialoka_ui.dart';

enum _Status { success, normal, muted }

const _events = [
  (status: _Status.success, title: 'Disetujui', time: '12 Nov 2026, 14.20', text: 'Lisensi cover siap dipakai.'),
  (status: _Status.normal, title: 'Ditinjau', time: '10 Nov 2026, 10.05', text: 'Tim kami memeriksa dokumenmu.'),
  (status: _Status.normal, title: 'Dokumen diterima', time: '8 Nov 2026, 16.40', text: 'Surat kuasa dan master audio lengkap.'),
  (status: _Status.muted, title: 'Diajukan', time: '5 Nov 2026, 09.12', text: 'Kamu mengajukan clearance.'),
];

class TimelineDemo extends StatelessWidget {
  const TimelineDemo({super.key});

  @override
  Widget build(BuildContext context) {
    final theme = ShadTheme.of(context);
    final c = context.sosialoka;
    Color dot(_Status s) => switch (s) {
      _Status.success => c.success,
      _Status.normal => theme.colorScheme.primary,
      _Status.muted => theme.colorScheme.mutedForeground,
    };
    return ConstrainedBox(
      constraints: const BoxConstraints(maxWidth: 384),
      child: Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          for (final (index, e) in _events.indexed)
            Semantics(
              label: '${e.title}, ${e.time}. ${e.text}',
              child: ExcludeSemantics(
                child: IntrinsicHeight(
                  child: Row(
                    crossAxisAlignment: CrossAxisAlignment.stretch,
                    children: [
                      SizedBox(
                        width: 16,
                        child: Column(
                          children: [
                            const SizedBox(height: 4),
                            Container(
                              width: 10,
                              height: 10,
                              decoration: BoxDecoration(color: dot(e.status), shape: BoxShape.circle),
                            ),
                            if (index < _events.length - 1)
                              Expanded(child: Container(width: 1, color: theme.colorScheme.border)),
                          ],
                        ),
                      ),
                      const SizedBox(width: 12),
                      Expanded(
                        child: Padding(
                          padding: const EdgeInsets.only(bottom: 20),
                          child: Column(
                            crossAxisAlignment: CrossAxisAlignment.start,
                            children: [
                              Text(e.time, style: theme.textTheme.muted),
                              Text(e.title, style: const TextStyle(fontWeight: FontWeight.w500)),
                              Text(e.text, style: theme.textTheme.muted),
                            ],
                          ),
                        ),
                      ),
                    ],
                  ),
                ),
              ),
            ),
        ],
      ),
    );
  }
}
```

## Instal

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/timeline.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/timeline.json
```

## Aksesibilitas

- Timeline adalah daftar; beri nama dengan `aria-label`, misalnya "Riwayat clearance Senja di Kota".
- Judulnya menyebut apa yang terjadi, jadi warna titik tidak pernah menjadi satu-satunya tanda.
- Titik dan garis disembunyikan dari pembaca layar. Di Flutter, setiap kejadian adalah satu node `Semantics` berisi judul, waktu, dan teksnya.
