Initial commit: timeline-elements-ui library

Angular 19 component library for timelines and event tracking: timeline, Gantt chart, event cards, date markers, connectors, and custom event templates. Includes signal-based services, SCSS design tokens with dark mode, and TypeScript type definitions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-13 21:58:25 +10:00
commit a07edd485b
78 changed files with 7681 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,194 @@
+# 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