Frontend

Version History Panel

Relevant source files

The following files were used as context for generating this wiki page:

The Version History Panel is a specialized side-sheet component designed to provide a comprehensive audit trail for specific entity records. It visualizes changes over time by fetching audit logs from the backend, parsing deltas between record states, and presenting them in a chronological timeline.

Overview and Integration

The panel is implemented in VersionHistoryPanel.svelte src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:1-33 and is registered within the global SheetHost.svelte src/lib/shell/sheets/SheetHost.svelte:16-24 under the ID entity.versionHistory. It is typically invoked via the openSheet utility from the sheet-manager src/lib/shell/sheets/sheet-manager.svelte.ts:74-92.

Data Flow Diagram

This diagram illustrates the lifecycle of an audit request from the UI interaction to the paginated API fetch.

Code
graph TD
    subgraph "UI Layer"
        A["User Clicks 'Version History'"] --> B["openSheet('entity.versionHistory', {entity, rowUuid})"]
    end

    subgraph "Panel Component (VersionHistoryPanel.svelte)"
        B --> C["loadVersionHistory()"]
        C --> D["apiFetch('/api/v1/entities/{entity}/{uuid}/audit')"]
        D --> E["Parse JSON Response"]
        E --> F["Update versionHistoryData $state"]
        F --> G["formatAuditDelta(delta, action)"]
    end

    subgraph "Backend API"
        D -.-> H["/api/v1/entities/:entity/:uuid/audit"]
        H -.-> I["Return Paginated Audit Logs"]
    end
    
    G --> J["Render Timeline Component"]

Sources: src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:53-76, src/lib/shell/sheets/sheet-manager.svelte.ts:34-39

Technical Implementation

Audit Log Fetching

The panel utilizes apiFetch to retrieve data from the audit endpoint. It supports pagination through versionHistoryPage and versionHistoryLimit states src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:35-41.

Initial Load: loadVersionHistory resets the state and fetches the first page src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:53-76.
Incremental Load: loadMoreVersionHistory appends new entries to the existing versionHistoryData array when the user scrolls to the bottom src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:78-100.

Delta Parsing Pipeline

The core logic resides in formatAuditDelta, which transforms raw JSON diffs into human-readable descriptions.

Field Translation: Keys are translated using the entities.versionHistory.field.{field} namespace src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:200-201.
Type Resolution: The function identifies special field types (badges, dates, colors) to apply specific formatting src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:179-195.
Value Comparison: It maps "from" (old) and "to" (new) values. If a field is a badge type, it uses badgeClassesFromToken to resolve semantic colors src/lib/colors/badge.ts:1-10.

Semantic Action Coloring

Audit actions are visually categorized using Tailwind CSS classes to indicate the nature of the change:

Action	Semantic Color	Tailwind Classes	Icon
`CREATE` / `INSERT`	Emerald (Success)	`text-emerald-600`	`CircleCheckBig`
`UPDATE`	Sky (Info)	`text-sky-600`	`Info`
`RESTORE`	Amber (Warning)	`text-amber-600`	`AlertTriangle`
`DELETE` / `SOFT_DELETE`	Red (Danger)	`text-red-600`	`AlertCircle`
`HARD_DELETE`	Red (Critical)	`text-red-700`	`CircleX`

Sources: src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:102-148

Component Architecture

The panel is built using a composition of Shadcn-Svelte primitives and domain-specific UI components.

UI Structure Map

This diagram maps the visual sections of the panel to their corresponding code components and logic.

Code
graph LR
    subgraph "VersionHistoryPanel (Code Space)"
        SH["SheetHeader.svelte"]
        TL["Timeline.svelte"]
        TI["TimelineItem.svelte"]
        TC["TimelineContent.svelte"]
        FAD["formatAuditDelta()"]
        GAC["getAuditActionColorClass()"]
    end

    subgraph "Visual Interface (Natural Language Space)"
        Header["Panel Title & Close Button"]
        Track["Vertical Continuity Line"]
        Node["Action Icon (Circle/Triangle/etc)"]
        Body["Change Description (Field A: X -> Y)"]
        User["'Changed By' Metadata"]
    end

    SH --- Header
    TL --- Track
    TI --- Node
    TC --- Body
    FAD --- Body
    GAC --- Node

Sources: src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:20-21, src/lib/shell/sheets/SheetHeader.svelte:1-21, src/lib/components/ui/timeline/timeline.svelte:1-17

Timeline Components

The history is rendered using a Timeline component set:

Timeline.Root: Provides the relative container and the vertical absolute line src/lib/components/ui/timeline/timeline.svelte:14-17.
Timeline.Item: A single audit entry wrapper src/lib/components/ui/timeline/timeline-item.svelte.
Timeline.Separator: The circular node containing the action icon, styled via getAuditActionBorderClass src/lib/components/ui/timeline/timeline-separator.svelte:14-19.
Timeline.Content: The container for the audit details, including the user who performed the action and the formatted delta src/lib/components/ui/timeline/timeline-content.svelte:14-17.

State Management

The panel uses Svelte 5 runes for reactivity:

$state: Manages versionHistoryData, loading status, and the expandedEntries Set for toggling detailed diff views src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:35-42.
$derived: (Indirectly via SheetHost) ensures props like entity and rowUuid are reactive when the sheet is replaced src/lib/shell/sheets/SheetHost.svelte:27-29.

Sources: src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:35-51, src/lib/shell/sheets/sheet-manager.svelte.ts:64-72

Last modified on July 13, 2026

User Profile & Security Settings Versioning & GitFlow