Event Timeline

Preview

A full single-well lifecycle. Filter by lifecycle group with the chips, then click any event to open its detail dialog — summary, tags, description, details, and attachments (images preview inline; files download). The workover carries an operations log via renderDetail.

import { EventTimeline, EventActivityLog } from "@aai-agency/og-components";
import { sampleWellEvents } from "@aai-agency/og-components/sample-data";

<EventTimeline
  events={sampleWellEvents}
  title="Well history"
  renderDetail={(event) =>
    Array.isArray(event.meta?.steps) ? (
      <EventActivityLog
        title="Operations log"
        maxHeight={168}
        entries={event.meta.steps}
      />
    ) : null
  }
/>

Overview

The default vertical feed is a grouped history list — a muted date column beside each entry: a color-coded status dot, the title, a soft type tag (shown only when it adds information beyond the title), a duration and date range for spans, a paperclip count when an event has attachments, and the description. Events are grouped into period sections (year or month, chosen from the span) on subtle dividers, and the feed scrolls internally past maxHeight.

A group filter (on by default) sits above the feed: soft toggle chips for the five lifecycle groups, with the header showing "N of M". Set orientation="horizontal" for a compact, time-aligned lane that lines up directly beneath a chart, with optional swim-lanes per workstream.

The package ships three exports: EventTimeline (the history), EventDetailDialog (the detail modal, usable on its own), and EventActivityLog (a compact, time-based, internally-scrollable log primitive).

Detail dialog

Clicking a row opens an accessible modal (Radix Dialog) laid out like a filled-out form: an optional AI-generated Summary section (marked with an AI tag), then name, date, tags, description, a details / property list, and attachments — images preview inline, other files show as cards with an extension badge, name, and size. Click a card to view the file in a new tab or use its download control to save it. The body scrolls, so long records fit. EventDetailDialog is exported on its own, so you can open the same dialog from any list, table, or map marker you already have — no timeline required.

import { useState } from "react";
import { EventDetailDialog, type WellEvent } from "@aai-agency/og-components";

// The same dialog EventTimeline opens on click, available standalone —
// drive it from any list, table, or map marker you already have.
function AssetEvents({ events }: { events: WellEvent[] }) {
  const [selected, setSelected] = useState<WellEvent | null>(null);
  return (
    <>
      {events.map((event) => (
        <button key={event.id} onClick={() => setSelected(event)}>
          {event.title}
        </button>
      ))}
      <EventDetailDialog event={selected} onClose={() => setSelected(null)} />
    </>
  );
}

AI summary

Every event can carry a short summary that leads its detail dialog, marked with an AI tag. Set event.summary to whatever your pipeline generates from the full description, and the dialog puts it up top so nobody has to read the whole report first. Here is the workover exactly as its dialog opens, summary first:

Operations log

EventActivityLog is a reusable primitive — a compact, time-based, internally-scrollable log ({ time?, label, description?, color? }[]) for operations logs, run histories, or audit trails. Drop it into a dialog via renderDetail, or use it anywhere on its own. Only primitive meta values render in the built-in Details list, so arrays and objects (like a step log) are yours to lay out.

import { EventTimeline, EventActivityLog } from "@aai-agency/og-components";

// renderDetail injects your own section(s) into the dialog per event.
// Only primitive meta values render in the built-in Details list;
// arrays/objects (like a step log) are yours to lay out here.
<EventTimeline
  events={events}
  renderDetail={(event) =>
    Array.isArray(event.meta?.steps) ? (
      <EventActivityLog title="Operations log" maxHeight={168} entries={event.meta.steps} />
    ) : null
  }
/>

Installation

pnpm add @aai-agency/og-components

The Event Timeline is self-contained (inline-styled, so no stylesheet import is required) and pulls in @radix-ui/react-dialog for the accessible detail modal.

Usage

Drop-in demo with the bundled single-well lifecycle dataset:

import { EventTimeline } from "@aai-agency/og-components";
import { sampleWellEvents } from "@aai-agency/og-components/sample-data";

// Vertical history feed (default). Grouped by period, filterable by
// lifecycle group. Click any row to open its detail dialog.
export function WellHistory() {
  return <EventTimeline events={sampleWellEvents} title="Well history" maxHeight={460} />;
}

Extend the dialog (renderDetail)

Inject custom sections per event — an operations log, a sub-table, a chart — without forking the component.

import { EventTimeline, EventActivityLog } from "@aai-agency/og-components";

// renderDetail injects your own section(s) into the dialog per event.
// Only primitive meta values render in the built-in Details list;
// arrays/objects (like a step log) are yours to lay out here.
<EventTimeline
  events={events}
  renderDetail={(event) =>
    Array.isArray(event.meta?.steps) ? (
      <EventActivityLog title="Operations log" maxHeight={168} entries={event.meta.steps} />
    ) : null
  }
/>

The dialog on its own

Drive EventDetailDialog from your own UI — pass the selected event, or null to close.

import { useState } from "react";
import { EventDetailDialog, type WellEvent } from "@aai-agency/og-components";

// The same dialog EventTimeline opens on click, available standalone —
// drive it from any list, table, or map marker you already have.
function AssetEvents({ events }: { events: WellEvent[] }) {
  const [selected, setSelected] = useState<WellEvent | null>(null);
  return (
    <>
      {events.map((event) => (
        <button key={event.id} onClick={() => setSelected(event)}>
          {event.title}
        </button>
      ))}
      <EventDetailDialog event={selected} onClose={() => setSelected(null)} />
    </>
  );
}

Align a lane under a chart

Set orientation="horizontal" and match domain and padding to the chart so the events sit directly under the plot.

import { Chart } from "@aai-agency/og-components";
import { EventTimeline } from "@aai-agency/og-components";

// A compact lane that lines up beneath a chart. Pass the chart's
// visible X window as domain and match padding to its plot inset.
<Chart kind="line" series={production} height={280} />
<EventTimeline
  events={events}
  orientation="horizontal"
  domain={[windowStart, windowEnd]}
  padding={{ left: 56, right: 14 }}
  showLog={false}
/>

Props

Sample data

The package ships a full single-well lifecycle history — permits through workover — with per-event details, an AI-style summary, inline-previewable image attachments, a downloadable CSV, and a step log for the operations-log demo. Use it to prototype without synthesizing your own events:

import { sampleWellEvents } from "@aai-agency/og-components/sample-data";
import type { WellEvent } from "@aai-agency/og-components";

// WellEvent[] — a single well's lifecycle, ready to pass to <EventTimeline events={...} />