Build a history feed — actor, action, diff, time

Overview

A read-only timeline of immutable events: avatar, actor name, verb phrase, target, timestamp. Tap an event to expand a before/after diff. Filter by actor, action, or date range.

Every operator app needs an audit log. Customers ask "who changed this?" and the answer has to be uncontested — not "probably Tendai." History gives you that defense, but only if it's read-only. The moment a row is editable, the timeline is no longer evidence.

History is read-only — never edit in place. An editable history breaks the trust contract: if rows can be rewritten, they can't testify. Correct mistakes by appending new events, not by mutating old ones.

Skip this recipe if what you actually need is a recent-activity widget — that's the simple list recipe. Skip if you need to mutate (then it's a transaction list, not history). History feeds are for legal/compliance, not UX nostalgia.

What you'll build

Default timeline, expanded diff, filter chips.

Required pieces

Avatar, row, filter chips, a button. Date-bucket the rows.

@corelithzw/react exports used here: Avatar, RowCard, FilterChips, Button, Spinner. Reuse the bucketing function from the lists-grouped-by-date recipe.

Step-by-step build

An event has an actor, a verb (the action key), a target, an ISO timestamp, and an optional changes object for the diff. The action is an enum string — never a free-form sentence, because filters need to match on it.

Build the sentence in a helper, not inline in the row. A single function maps (action, targetLabel) to the human verb phrase — this is the only place to change copy when product changes their mind about wording.

For each changed field, show field: before → after. Don't truncate before/after values — if an audit row truncates the change, it's not an audit row. If a field is too long, line-wrap. The user came here for the truth.

One filter state, one predicate, one filtered array. The CSV export writes the same filtered array — so what the user exports matches what they see. Anything else is a footgun ("I exported but only got 3 rows" — yes, your filter was still on).

Final composition

~140 lines. Filter chips, day buckets, expandable diff, CSV export. Pull-to-refresh is variant A.

Variations

Three forks. Same read-only spirit.

const onTouchMove = (e) => {
  if (scroll.scrollTop > 0) return;
  const dy = e.touches[0].clientY - startY;
  if (dy > 60 && !refreshing) onRefresh();
};

<HistoryFeed
  events={events.filter(
    e => e.objectId === id
  )}
  // hide actor chips entirely
/>

<li className="evt-compact">
  <span className="actor">
    {e.actor.name}
  </span>
  <span>{verbPhrase(…)}</span>
  <time>{e.at}</time>
</li>

Accessibility

Audit logs are evidence — accessibility is non-negotiable.

• Expand toggle is a real button with aria-expanded. Not a div with a click handler — assistive tech needs to know the row is interactive.
• <time dateTime> on every timestamp. Machine-readable ISO plus human-readable text; screen readers read both correctly.
• Diff uses <dl> <dt> <dd>. A description list is semantically the right shape for field → value-change pairs.
• Filter chips announce their state. Use aria-pressed on chip buttons so screen readers say "Tendai, pressed" when active.
• Empty filter result speaks. "No events match these filters." in a role="status" region — silent empty states are confusing.
• CSV download is a button, not a link. A button triggers a blob download; a link to # with a JS handler is a focus trap.

Related recipes