@memberjunction/ng-record-changes

Angular components for browsing and restoring a record's change history. Renders the RecordChange timeline as a slide-in panel with type-aware diffs, version-label chips, restore lineage, and a reusable preview panel for the actual restore operation.

flowchart LR
    subgraph Timeline["RecordChangesComponent"]
        TL[Slide-in panel] --> CARDS[Date-grouped change cards]
        CARDS --> DIFFS[Type-aware diffs
boolean / date / number / text]
        CARDS --> CHIP[Restored-from lineage chip]
        FILTERS[Conditional filter pills] --> POP[Overflow popover
when 3+ pills]
    end

    subgraph Restore["RestorePreviewPanelComponent"]
        PV[Slide-in preview] --> ROWS[Field-by-field rows
with checkboxes]
        ROWS --> MODE{Mode}
        MODE -->|live| DIFF[current vs snapshot]
        MODE -->|undelete| SNAP[snapshot only]
        ROWS --> COMMIT[BeforeRestoreCommit
cancelable]
    end

    Timeline -- "user clicks Restore" --> Restore
    Restore -- "RestoreConfirmed event
(host applies + saves)" --> HOST[Host component]

    style Timeline fill:#264FAF,stroke:#1e3f8c,color:#fff
    style Restore fill:#7c3aed,stroke:#5b21b6,color:#fff
    style HOST fill:#16a34a,stroke:#15803d,color:#fff
Copy

Installation

npm install @memberjunction/ng-record-changes
Copy

Usage

Import the Module

import { RecordChangesModule } from '@memberjunction/ng-record-changes';

@NgModule({
  imports: [RecordChangesModule]
})
export class MyModule { }
Copy

Timeline + Restore (the typical case)

<mj-record-changes
  [record]="myEntity"
  [AllowRestore]="true"
  (dialogClosed)="showHistory = false"
  (RestoreRequested)="onRestoreRequested($event)">
</mj-record-changes>
Copy

async onRestoreRequested(event: RestoreVersionEvent) {
  // Apply each selected snapshot field
  for (const fv of event.FieldValues) {
    this.myEntity.Set(fv.FieldName, fv.Value);
  }
  // Mark the next save as a restore so the provider populates lineage columns
  this.myEntity.SetRestoreContext(event.SourceChangeID, event.Reason);
  try {
    await this.myEntity.Save();
  } finally {
    this.myEntity.ClearRestoreContext();
  }
}
Copy

The host is responsible for the actual save so consumers can intercept (custom approval, audit logging, etc.). record-form-container already wires this end-to-end.

Standalone Restore Preview (un-delete from a Recycle Bin)

<mj-restore-preview-panel
  [Visible]="showPreview"
  [Mode]="'undelete'"
  [RecordChange]="deletedChange"
  [EntityName]="'Customers'"
  (RestoreConfirmed)="onUndelete($event)"
  (RestoreCancelled)="showPreview = false">
</mj-restore-preview-panel>
Copy

API Reference

RecordChangesComponent (mj-record-changes)

The slide-in timeline of all changes to a single record. Hosts the reusable RestorePreviewPanelComponent for the actual restore confirmation flow.

Inputs

Outputs

12-Month Activity Sparkline & Collapsible Version Labels

• Activity Sparkline (ActivityChartBuckets): When a record has 2+ changes, a collapsible 12-month bar chart appears in the timeline header showing monthly change volume. Clicking any month bar filters the timeline to changes in that month (SelectedMonthKey); clicking again clears the filter.
• Compact Collapsible Version Labels (ShowLabelsSection): Version labels are tucked behind a single-line header pill (Labels (N) + + Label quick action) and stay collapsed by default when 0 labels exist so the change timeline gets maximum vertical space.

RestoreVersionEvent

Conditional filter pills

The filter bar renders only chips for change types/sources that actually exist in the loaded data — empty types never show. When more than two conditional chips would render they collapse into a "More filters ▾" popover with checkboxes. The "All" chip is always present.

Lineage chip

Change rows where RestoredFromID is populated render a violet "Restored from {time} by {user}" chip. Clicking the chip scrolls to and highlights the source row in the same timeline.

RestorePreviewPanelComponent (mj-restore-preview-panel)

Reusable slide-in that previews a restore operation against a historical MJRecordChangeEntity and lets the user confirm with field-level granularity. Used by both RecordChangesComponent (for live-record restores) and RecycleBinComponent (for un-delete inserts).

Inputs

Outputs

RestoreCommitEvent

Semantic correctness

The preview compares the full snapshot captured in the source change's FullRecordJSON to the current live record (or to nothing in undelete mode). It does NOT roll back a single delta — restoring v2 means "make the record look like it did at v2", not "undo v3's changes".

This also means any change row is a valid restore target: Create (the original state), Update (post-update state), Snapshot (an explicit point-in-time capture from the Version Label system), or Delete (state before deletion — used by the Recycle Bin).

Activity Over Time — Burst-Aware Cluster Strip (Time-Gap Compression & Multi-Year Zoom)

Record change histories are often highly irregular over time (for example, an initial creation burst, months of quiet, and a recent cluster of edits) or span several years with hundreds of changes. <mj-record-changes> embeds the reusable <mj-burst-cluster-strip> (MJBurstClusterStripComponent) from @memberjunction/ng-ui-components:

• Session Burst Clustering & Non-Linear Gap Compression: Groups adjacent changes into active editing sessions separated by compressed ⋯ 11 mos quiet ⋯ gap connectors instead of leaving 80%+ of linear time buckets empty.
• Adaptive Multi-Year Scaling & Semantic Click-to-Zoom: When raw bursts exceed BurstEraZoomThreshold (default 10) across multiple months/years, the strip automatically coalesces into Year or Month era cards (2023, 2024, 2025, 2026). Clicking any era zooms the strip into that period's bursts with a ← All (N) breadcrumb pill.
• Configurable Grouping Inputs on <mj-record-changes>:
  • [BurstResolution]: 'auto' | 'session' | 'day' | 'week' | 'month' | 'quarter' | 'year' (default 'auto')
  • [BurstCoalesceStrategy]: 'adaptive-era' | 'merge-closest' (default 'adaptive-era')
  • [BurstSessionGapHours]: number (default 6)
  • [BurstMaxClusters]: number (default 5)
  • [BurstEraZoomThreshold]: number (default 10)
  • [AllowBurstZoom]: boolean (default true)

Type Exports

import {
  // Timeline
  RecordChangesComponent,
  RecordChangesModule,
  RestoreVersionEvent,
  FieldChangeInfo,
  DateGroup,
  FilterPill,

  // Restore Preview
  RestorePreviewPanelComponent,
  RestorePreviewMode,
  RestoreFieldRow,
  RestoreCommitEvent,
  BeforeRestoreCommitEvent,
} from '@memberjunction/ng-record-changes';
Copy

Dependencies

Runtime Dependencies

Peer Dependencies

• @angular/common ^21.x
• @angular/core ^21.x
• @angular/forms ^21.x

Build

cd packages/Angular/Generic/record-changes
npm run build
Copy

License

Business Source License 1.1 — see LICENSE for details.