# Timeline Component

## Objective

Give the app one way to render a chronological run of events.

A reusable timeline for ordered events — activity feeds, audit trails, order history, comment threads.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Identify every place the app already lists things in time order and unify them, rather than leaving the order history, the audit log, and the activity feed as three unrelated layouts.
2. Define a deterministic sort for events sharing a timestamp — a secondary key such as the record identifier — so the same data always renders in the same order.
3. Give each entry an actor, an action, an object, and a time, and let any of the four be absent without the row collapsing.
4. Group entries by day or by burst for scanning, but keep the exact time available on each entry rather than replacing it with the group heading.
5. Do not resolve event descriptions by looking up live records at render time. An audit entry must still read correctly after the record it refers to has been renamed or deleted.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- Two events written in the same second must not swap places between renders — order them by a stable tiebreaker so pagination does not duplicate or drop an entry.
- Grouping by day is a scanning aid, not a replacement for precision; a user auditing an incident needs the exact timestamp, so keep it on the entry or on hover and in the title attribute.
- A deleted user or a deleted record must still render its entry, showing a preserved name or a neutral placeholder rather than a blank, a null, or a broken avatar.
- On narrow screens the connector rail, avatars, and timestamps compete for width — drop to a single column with the time above the entry rather than truncating the description.
- Relative times such as two hours ago must be rendered in the reader's time zone and must not go stale on a page left open, and they must never be the only representation of the time.
- A long timeline needs paging or windowing that loads older entries without jumping the scroll position of what the user is already reading.
- An empty timeline needs copy explaining that nothing has happened yet, distinct from the state where a filter has excluded everything.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] All chronological lists in the app render through the same timeline.
- [ ] Events sharing a timestamp appear in a stable order across reloads and pages.
- [ ] Every entry exposes its exact time in the reader's time zone.
- [ ] Entries referring to deleted actors or records render intact with a placeholder.
- [ ] The timeline reads as a single column on narrow screens with no truncated descriptions.
- [ ] Loading older entries preserves the current scroll position.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.