# Timeline

## Overview

A vertical sequence of events displayed chronologically, each with a timestamp, title, and optional description. Used in activity logs, audit trails, case histories, and notification feeds.

---

## When to Use

- Activity logs and audit trails
- Event histories on records (status changes, actions)
- Notification feeds on dashboards

---

## Anatomy

```
<Timeline>
  <TimelineItem>
    <TimelineDot variant="success" icon={<CheckCircle />} />
    <TimelineContent>
      <TimelineTime>Today, 09:00</TimelineTime>
      <TimelineHeading>Event Title</TimelineHeading>
      <TimelineDescription>Optional description</TimelineDescription>
    </TimelineContent>
  </TimelineItem>
</Timeline>
```

---

## TimelineDot Variants

| Variant       | Color         | Usage                    |
| ------------- | ------------- | ------------------------ |
| `default`     | Muted         | Neutral events           |
| `primary`     | Primary brand | Highlighted events       |
| `success`     | Green         | Completed actions        |
| `info`        | Blue          | Informational events     |
| `warning`     | Amber         | Caution events           |
| `destructive` | Red           | Errors or failures       |
| `outline`     | Border only   | Pending or future events |

---

## Sub-components

| Component             | Description                                    |
| --------------------- | ---------------------------------------------- |
| `Timeline`            | Root `<ol>` with the left border line          |
| `TimelineItem`        | `<li>` wrapper for a single event              |
| `TimelineDot`         | Colored dot or icon badge on the timeline line |
| `TimelineContent`     | Content area to the right of the dot           |
| `TimelineHeading`     | Event title (`<h3>`)                           |
| `TimelineTime`        | Timestamp (`<time>`)                           |
| `TimelineDescription` | Optional description paragraph                 |

---

## Examples

```tsx
import {
  Timeline,
  TimelineItem,
  TimelineDot,
  TimelineContent,
  TimelineHeading,
  TimelineTime,
  TimelineDescription,
} from 'xertica-ui/ui';
import { CheckCircle, AlertCircle, LogIn, Clock } from 'lucide-react';

<Timeline>
  <TimelineItem>
    <TimelineDot variant="default" icon={<LogIn className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Login</TimelineHeading>
      <TimelineTime>Today, 09:00</TimelineTime>
      <TimelineDescription>User logged in from Chrome on macOS</TimelineDescription>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="success" icon={<CheckCircle className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Password Changed</TimelineHeading>
      <TimelineTime>Yesterday, 16:32</TimelineTime>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="destructive" icon={<AlertCircle className="size-4" />} />
    <TimelineContent>
      <TimelineHeading>Security Alert</TimelineHeading>
      <TimelineTime>Mon, 10:15</TimelineTime>
      <TimelineDescription>Suspicious login attempt blocked</TimelineDescription>
    </TimelineContent>
  </TimelineItem>

  <TimelineItem>
    <TimelineDot variant="outline" />
    <TimelineContent>
      <TimelineHeading>Pending Review</TimelineHeading>
      <TimelineTime>Scheduled</TimelineTime>
    </TimelineContent>
  </TimelineItem>
</Timeline>;
```

---

## AI Rules

- Always compose: `Timeline > TimelineItem > (TimelineDot + TimelineContent)`.
- `TimelineTime` renders a `<time>` element — pass a pre-formatted display string, not a Date object.
- Use `TimelineDot variant="outline"` for pending or future events.
- Pass `icon` to `TimelineDot` for large icon dots; omit for small colored dots.
- For large timelines, wrap in `<ScrollArea className="h-[400px]">`.