timeline-elements-ui/README.md

# Timeline Elements UI

Angular 19 components for timeline, activity feed, audit trail, changelog, and Gantt chart displays powered by @sda/base-ui.

## Features

- **Timeline** — Vertical timeline with alternating layouts, grouping, and sorting
- **Horizontal Timeline** — Scrollable horizontal timeline with nav arrows
- **Activity Feed** — Social-style activity stream with avatars and load-more pagination
- **Audit Trail** — Comprehensive audit log with search, filter, and expandable change diffs
- **Changelog** — Version-based changelog with categorized entries and breaking change badges
- **Gantt Chart** — Interactive Gantt chart with zoom levels, progress bars, and today line
- **Signal API** — Built with Angular 19 signals (`input()`, `output()`, `computed()`, `signal()`)
- **Standalone** — All components are standalone with OnPush change detection
- **Themeable** — CSS custom properties with base-ui token fallbacks
- **Dark Mode** — Full dark mode support via `prefers-color-scheme`
- **Accessible** — ARIA labels, keyboard navigation, focus management

## Installation

```bash
npm install @sda/timeline-elements-ui @sda/base-ui
```

## Quick Start

```typescript
import { Component } from '@angular/core';
import { TlTimelineComponent, type TlTimelineItem } from '@sda/timeline-elements-ui';

@Component({
  standalone: true,
  imports: [TlTimelineComponent],
  template: `
    <tl-timeline
      [items]="events"
      layout="left"
      [groupByDate]="true"
      (itemClick)="onItemClick($event)"
    />
  `
})
export class AppComponent {
  events: TlTimelineItem[] = [
    {
      id: '1',
      title: 'Tenancy started',
      description: 'John Doe moved in',
      date: new Date('2024-01-01'),
      icon: 'home',
      status: 'completed'
    }
  ];

  onItemClick(event: any) {
    console.log('Clicked:', event.item);
  }
}
```

## Components

### `tl-timeline`
Vertical timeline with markers and connectors.

**Inputs:**
- `items` — Timeline items (required)
- `layout` — 'left' | 'right' | 'alternating'
- `markerSize` — 'sm' | 'md' | 'lg'
- `connectorStyle` — 'solid' | 'dashed' | 'dotted'
- `sortDirection` — 'asc' | 'desc'
- `groupByDate` — Group items by date labels
- `animate` — Animate item entry
- `loading` — Show skeleton loaders
- `emptyMessage` — Message when no items

**Outputs:**
- `itemClick` — Emits when item is clicked
- `itemHover` — Emits when item is hovered

### `tl-horizontal-timeline`
Horizontal scrollable timeline.

**Inputs:**
- `items` — Timeline items (required)
- `markerSize`, `connectorStyle`, `sortDirection` — Same as `tl-timeline`
- `scrollable`, `showNavArrows`, `loading`, `emptyMessage`

**Outputs:**
- `itemClick`

### `tl-activity-feed`
Activity stream with avatars and pagination.

**Inputs:**
- `items` — Activity items (required)
- `pageSize` — Items per page
- `showLoadMore`, `showUnreadIndicator`, `groupByDate`, `loading`, `emptyMessage`

**Outputs:**
- `activityClick`, `actorClick`, `loadMore`

### `tl-audit-trail`
Audit log with search, filter, and expandable diffs.

**Inputs:**
- `entries` — Audit entries (required)
- `pageSize`, `searchable`, `filterable`, `expandable`, `showSeverityIcons`, `loading`, `emptyMessage`, `serverSide`

**Outputs:**
- `entryClick`, `filterChange`, `pageChange`

### `tl-changelog`
Version-based changelog.

**Inputs:**
- `versions` — Changelog versions (required)
- `collapsible`, `expandLatest`, `showCategoryBadges`, `showBreakingBadge`, `loading`, `emptyMessage`

**Outputs:**
- `versionClick`, `entryClick`

### `tl-gantt-chart`
Interactive Gantt chart.

**Inputs:**
- `tasks` — Gantt tasks (required)
- `dependencies`, `zoomLevel`, `rowHeight`, `showDependencies`, `showProgress`, `showTodayLine`, `loading`, `emptyMessage`

**Outputs:**
- `taskClick`, `taskResize`, `taskMove`, `zoomChange`, `scroll`

## Configuration

```typescript
import { provideTimelineConfig } from '@sda/timeline-elements-ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideTimelineConfig({
      locale: 'en-US',
      relativeTime: true,
      animate: true,
      timeline: {
        layout: 'left',
        markerSize: 'md',
        connectorStyle: 'solid',
        sortDirection: 'desc',
        groupByDate: false,
      },
      activity: {
        pageSize: 20,
        showUnreadIndicator: true,
        groupByDate: true,
      },
      audit: {
        pageSize: 25,
        searchable: true,
        filterable: true,
        expandable: true,
        showSeverityIcons: true,
      },
      gantt: {
        zoomLevel: 'week',
        rowHeight: 40,
        showDependencies: true,
        showProgress: true,
        showTodayLine: true,
      },
    }),
  ],
};
```

## Styling

All components use CSS custom properties with base-ui token fallbacks:

```scss
:root {
  --tl-bg: var(--color-bg-primary, #ffffff);
  --tl-text: var(--color-text-primary, #111827);
  --tl-border: var(--color-border-primary, #e5e7eb);
  --tl-marker-bg: var(--color-primary-500, #3b82f6);
  --tl-status-completed: #10b981;
  --tl-status-active: #3b82f6;
  --tl-status-error: #ef4444;
  // ... more tokens
}
```

## License

MIT