# Timeline

Use `ui-timeline` with an `items` array for data-driven feeds, or compose `ui-timeline-item` children when a row needs tags, buttons, or richer custom content. Each item supports title, timestamp, meta, description, icon markers, variants, and a pending state.

## Import
```ts
import { TimelineComponent, TimelineItemComponent, type TimelineItem } from 'ui';
```

## Activity feed
```ts
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { TimelineComponent, type TimelineItem } from 'ui';

@Component({
  selector: 'app-timeline-basic-demo',
  standalone: true,
  imports: [TimelineComponent],
  changeDetection: ChangeDetectionStrategy.Eager,
  template: `
    <div
      style="width:100%;max-width:36rem;padding:1rem;border:1px solid var(--color-neutral-stroke-rest);border-radius:1rem;background:var(--color-neutral-background-rest)"
    >
      <ui-timeline [items]="items" ariaLabel="Release activity" />
    </div>
  `,
})
export class TimelineBasicDemoComponent {
  protected readonly items: TimelineItem[] = [
    {
      id: 'draft',
      title: 'Draft saved',
      timestamp: '09:12',
      description: 'Campaign brief updated with new audience notes.',
      meta: 'Ava Lopez',
    },
    {
      id: 'review',
      title: 'Review requested',
      timestamp: '10:48',
      description: 'Legal and brand teams were added as reviewers.',
      meta: 'Marek Nowak',
      icon: 'person_mail',
      variant: 'info',
    },
    {
      id: 'approved',
      title: 'Approved for launch',
      timestamp: '14:05',
      description: 'All required reviewers signed off on the final version.',
      meta: 'System',
      icon: 'checkmark_circle',
      variant: 'success',
    },
  ];
}
```

## Semantic variants and pending state
```ts
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { TimelineComponent, type TimelineItem } from 'ui';

@Component({
  selector: 'app-timeline-variants-demo',
  standalone: true,
  imports: [TimelineComponent],
  changeDetection: ChangeDetectionStrategy.Eager,
  template: `
    <div
      style="width:100%;max-width:36rem;padding:1rem;border:1px solid var(--color-neutral-stroke-rest);border-radius:1rem;background:var(--color-neutral-background-rest)"
    >
      <ui-timeline [items]="items" size="small" ariaLabel="Deployment status" />
    </div>
  `,
})
export class TimelineVariantsDemoComponent {
  protected readonly items: TimelineItem[] = [
    {
      id: 'queued',
      title: 'Build queued',
      timestamp: '18:01',
      description: 'CI picked up commit 8f2a91 on main.',
      variant: 'secondary',
    },
    {
      id: 'running',
      title: 'Deploy in progress',
      timestamp: '18:04',
      description: 'Rolling out ui-showcase to staging.',
      variant: 'warning',
      icon: 'arrow_sync',
      pending: true,
    },
    {
      id: 'failed',
      title: 'Smoke tests failed',
      timestamp: '18:09',
      description: 'Checkout flow returned 500 on payment step.',
      variant: 'danger',
      icon: 'error_circle',
    },
    {
      id: 'resolved',
      title: 'Hotfix deployed',
      timestamp: '18:22',
      description: 'Payment gateway timeout handling restored service.',
      variant: 'success',
      icon: 'checkmark',
    },
  ];
}
```

## Audit trail
```ts
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { TimelineComponent, type TimelineItem } from 'ui';

@Component({
  selector: 'app-timeline-audit-demo',
  standalone: true,
  imports: [TimelineComponent],
  changeDetection: ChangeDetectionStrategy.Eager,
  template: `
    <div style="display:flex;flex-direction:column;gap:1rem;width:100%;max-width:42rem">
      <div
        style="display:flex;flex-direction:column;gap:0.25rem;padding:0.875rem 1rem;border:1px solid var(--color-neutral-stroke-rest);border-radius:1rem;background:var(--color-neutral-background2-rest)"
      >
        <div style="font-size:0.9375rem;font-weight:600">Customer record #48291</div>
        <div style="font-size:0.8125rem;color:var(--color-neutral-foreground2-rest)">
          Audit trail for billing profile changes in the last 24 hours.
        </div>
      </div>

      <div
        style="padding:1rem;border:1px solid var(--color-neutral-stroke-rest);border-radius:1rem;background:var(--color-neutral-background-rest)"
      >
        <ui-timeline [items]="items" ariaLabel="Customer audit trail" />
      </div>
    </div>
  `,
})
export class TimelineAuditDemoComponent {
  protected readonly items: TimelineItem[] = [
    {
      id: 'viewed',
      title: 'Record viewed',
      timestamp: 'Yesterday 16:14',
      meta: 'Support · Nina Kowalska',
      description: 'Opened billing details from the helpdesk console.',
      icon: 'eye',
      variant: 'info',
    },
    {
      id: 'email',
      title: 'Invoice email updated',
      timestamp: 'Yesterday 17:02',
      meta: 'Finance · Tomasz Wiśniewski',
      description: 'Changed primary invoice recipient to accounts@acme.io.',
      icon: 'mail',
      variant: 'primary',
    },
    {
      id: 'role',
      title: 'Permission denied',
      timestamp: 'Yesterday 17:18',
      meta: 'Security policy',
      description: 'Attempt to export full payment history was blocked.',
      icon: 'shield_error',
      variant: 'danger',
    },
    {
      id: 'note',
      title: 'Internal note added',
      timestamp: 'Today 08:41',
      meta: 'Support · Nina Kowalska',
      description: 'Customer confirmed the new billing contact during phone call.',
      icon: 'comment',
      variant: 'secondary',
    },
  ];
}
```

## Custom row content
```ts
import { Component, ChangeDetectionStrategy } from '@angular/core';
import { ButtonComponent, TagComponent, TimelineComponent, TimelineItemComponent } from 'ui';

@Component({
  selector: 'app-timeline-composition-demo',
  standalone: true,
  imports: [TimelineComponent, TimelineItemComponent, TagComponent, ButtonComponent],
  changeDetection: ChangeDetectionStrategy.Eager,
  template: `
    <div
      style="width:100%;max-width:38rem;padding:1rem;border:1px solid var(--color-neutral-stroke-rest);border-radius:1rem;background:var(--color-neutral-background-rest)"
    >
      <ui-timeline ariaLabel="Workspace activity with custom content">
        <ui-timeline-item
          title="Design review scheduled"
          timestamp="Today 09:30"
          meta="Product design"
          description="Review board for navigation refresh and command surfaces."
          icon="calendar"
          variant="primary"
        >
          <div style="display:flex;flex-wrap:wrap;gap:0.5rem;padding-top:0.25rem">
            <ui-tag text="Navigation" appearance="tint" variant="info" />
            <ui-tag text="High priority" appearance="outline" variant="warning" />
          </div>
        </ui-timeline-item>

        <ui-timeline-item
          title="Comments resolved"
          timestamp="Today 11:12"
          meta="Ava Lopez"
          description="All blocking feedback on the sidebar density pass is closed."
          icon="comment_checkmark"
          variant="success"
        />

        <ui-timeline-item
          title="Publish checklist"
          timestamp="Pending"
          meta="Release ops"
          description="Waiting for final screenshot diff and docs export."
          variant="warning"
          [pending]="true"
        >
          <ui-button type="button" variant="secondary" appearance="outline" size="small">
            Open checklist
          </ui-button>
        </ui-timeline-item>
      </ui-timeline>
    </div>
  `,
})
export class TimelineCompositionDemoComponent {}
```

## Accessibility

### Structure
The timeline renders as a list with one list item per event. Provide `ariaLabel` when multiple timelines appear on the same page.

### Timestamps and headings
Each event title is rendered as a heading level 3 inside its row. Timestamps use a `time` element for clearer scanning, even when the value is a relative label like `Pending`.

### Decorative rail
Markers and connector lines are marked `aria-hidden` so screen readers focus on the textual event content.