# Version History Panel # Version History Panel
Relevant source files The following files were used as context for generating this wiki page: - [src/lib/components/ui/choicebox/choicebox-indicator.svelte](src/lib/components/ui/choicebox/choicebox-indicator.svelte) - [src/lib/components/ui/dock/dock.svelte](src/lib/components/ui/dock/dock.svelte) - [src/lib/components/ui/timeline/index.ts](src/lib/components/ui/timeline/index.ts) - [src/lib/components/ui/timeline/timeline-content.svelte](src/lib/components/ui/timeline/timeline-content.svelte) - [src/lib/components/ui/timeline/timeline-date.svelte](src/lib/components/ui/timeline/timeline-date.svelte) - [src/lib/components/ui/timeline/timeline-description.svelte](src/lib/components/ui/timeline/timeline-description.svelte) - [src/lib/components/ui/timeline/timeline-item.svelte](src/lib/components/ui/timeline/timeline-item.svelte) - [src/lib/components/ui/timeline/timeline-separator.svelte](src/lib/components/ui/timeline/timeline-separator.svelte) - [src/lib/components/ui/timeline/timeline-title.svelte](src/lib/components/ui/timeline/timeline-title.svelte) - [src/lib/components/ui/timeline/timeline.svelte](src/lib/components/ui/timeline/timeline.svelte) - [src/lib/entity-list/sheets/panels/ColumnsPanel.svelte](src/lib/entity-list/sheets/panels/ColumnsPanel.svelte) - [src/lib/entity-list/sheets/panels/SearchInPanel.svelte](src/lib/entity-list/sheets/panels/SearchInPanel.svelte) - [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte](src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte) - [src/lib/shell/sheets/SheetHeader.svelte](src/lib/shell/sheets/SheetHeader.svelte) - [src/lib/shell/sheets/SheetHost.svelte](src/lib/shell/sheets/SheetHost.svelte) - [src/lib/shell/sheets/sheet-manager.svelte.ts](src/lib/shell/sheets/sheet-manager.svelte.ts)
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. ```mermaid 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. 1. **Field Translation**: Keys are translated using the `entities.versionHistory.field.{field}` namespace [src/lib/entity-list/sheets/panels/VersionHistoryPanel.svelte:200-201](). 2. **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](). 3. **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. ```mermaid 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]() ---