From 120485ee8df1e2dede5509b51e1e73a950a4e193 Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Mon, 8 Jun 2026 15:49:52 +0200
Subject: [PATCH] Refactor signature handling with SignatureCaptureDto

Introduced a new `SignatureCaptureDto` model to encapsulate
signature-related data and metadata, replacing the previous
`SignatureCapture` type in `EnvelopeViewer.razor`.

- Added `SignatureCaptureDto` in `SignatureCaptureDto.cs` with
  properties for signature image, signer name, position, and place.
- Updated `_capturedSignature` to use `SignatureCaptureDto` for
  consistency and maintainability.
- Refactored signature capture logic to initialize
  `SignatureCaptureDto` using object initializer syntax.
- Improved code clarity with detailed XML documentation for
  `SignatureCaptureDto`.

These changes enhance maintainability, readability, and ensure
a centralized model for signature-related data.
---
 .../Models/SignatureCaptureDto.cs             | 62 +++++++++++++++++++
 .../Pages/EnvelopeViewer.razor                | 11 +++-
 2 files changed, 70 insertions(+), 3 deletions(-)
 create mode 100644 EnvelopeGenerator.ReceiverUI/Models/SignatureCaptureDto.cs

diff --git a/EnvelopeGenerator.ReceiverUI/Models/SignatureCaptureDto.cs b/EnvelopeGenerator.ReceiverUI/Models/SignatureCaptureDto.cs
new file mode 100644
index 00000000..5c137cac
--- /dev/null
+++ b/EnvelopeGenerator.ReceiverUI/Models/SignatureCaptureDto.cs
@@ -0,0 +1,62 @@
+namespace EnvelopeGenerator.ReceiverUI.Models;
+
+/// <summary>
+/// Represents a captured signature with metadata created by the receiver in the signature popup.
+/// This model holds the signature image (as base64 data URL) along with signer information
+/// used for rendering applied signatures on the PDF canvas.
+/// </summary>
+/// <remarks>
+/// <b>Used in:</b> EnvelopeViewer.razor signature popup workflow
+/// <br/>
+/// <b>Creation:</b> User draws/types/uploads signature and fills required fields
+/// <br/>
+/// <b>Storage:</b> Session-only (Blazor component state, lost on page refresh)
+/// <br/>
+/// <b>Rendering:</b> Applied signatures display: Image + Separator + Name/Position/Place/Date
+/// </remarks>
+public sealed record SignatureCaptureDto
+{
+    /// <summary>
+    /// Base64-encoded data URL of the signature image.
+    /// <br/>
+    /// <b>Format:</b> <c>data:image/png;base64,iVBORw0KG...</c>
+    /// <br/>
+    /// <b>Source:</b> Canvas.toDataURL() from signature pad (draw/text/image tabs)
+    /// <br/>
+    /// <b>Usage:</b> Set as <c>img.src</c> in applied signature overlay
+    /// </summary>
+    public required string DataUrl { get; init; }
+
+    /// <summary>
+    /// Full name of the signer (first and last name).
+    /// <br/>
+    /// <b>Required:</b> Yes (validated in popup)
+    /// <br/>
+    /// <b>Display:</b> Bold text in applied signature block
+    /// <br/>
+    /// <b>Example:</b> "Max Mustermann"
+    /// </summary>
+    public required string FullName { get; init; }
+
+    /// <summary>
+    /// Job title or position of the signer.
+    /// <br/>
+    /// <b>Required:</b> No (optional field)
+    /// <br/>
+    /// <b>Display:</b> Normal weight text between name and place/date
+    /// <br/>
+    /// <b>Example:</b> "Geschäftsführer" or empty string
+    /// </summary>
+    public string Position { get; init; } = string.Empty;
+
+    /// <summary>
+    /// Location/place where the signature was created.
+    /// <br/>
+    /// <b>Required:</b> Yes (validated in popup)
+    /// <br/>
+    /// <b>Display:</b> Shown with current date in German format (dd.MM.yyyy)
+    /// <br/>
+    /// <b>Example:</b> "Berlin" ? rendered as "Berlin, 26.01.2025"
+    /// </summary>
+    public required string Place { get; init; }
+}
diff --git a/EnvelopeGenerator.ReceiverUI/Pages/EnvelopeViewer.razor b/EnvelopeGenerator.ReceiverUI/Pages/EnvelopeViewer.razor
index f983a507..4be1e5f3 100644
--- a/EnvelopeGenerator.ReceiverUI/Pages/EnvelopeViewer.razor
+++ b/EnvelopeGenerator.ReceiverUI/Pages/EnvelopeViewer.razor
@@ -506,8 +506,7 @@ int _unsignedSignatures = 0;
 int _currentSignatureIndex = 0;  // Åžu an hangi imzada (1-based)
 
 // Signature state
-record SignatureCapture(string DataUrl, string FullName, string Position, string Place);
-SignatureCapture? _capturedSignature;
+SignatureCaptureDto? _capturedSignature;
 bool _signaturePopupVisible = false;
 string? _popupValidationMessage;
 string _activeSignatureTab = SignatureTabDraw;
@@ -873,7 +872,13 @@ const int MaxThumbnailWidth = 400;
         }
 
         _popupValidationMessage = null;
-        _capturedSignature = new(signatureDataUrl, _signerFullName.Trim(), _signerPosition.Trim(), _signaturePlace.Trim());
+        _capturedSignature = new SignatureCaptureDto
+        {
+            DataUrl = signatureDataUrl,
+            FullName = _signerFullName.Trim(),
+            Position = _signerPosition.Trim(),
+            Place = _signaturePlace.Trim()
+        };
         _signaturePopupVisible = false;
         
         await InvokeAsync(StateHasChanged);