# Signature Field Formatting — WISAG Feedback

## Context

Customer feedback received from the new WISAG signFLOW project lead (email dated 3/7/2026).  
The signature stamp rendered inside the finalized PDF has layout issues that need to be addressed.

### Current State (screenshot from customer email)

```
Signiert von ___________
[ signature image       ]
Armin Schneider
C6B85E96A520C60...       ← certificate hash, too close to name
Bereichsleiter Kern-     ← position text wraps, no spacing to date
Anwendungen
Frankfurt am Main
23.06.2026, 17:13:42 GMT+2
```

### Issues Reported

1. **Spacing between name and certificate number** is too small — needs more vertical gap.
2. **Spacing between position/title and date/time** is too small — should be dynamic (expand with content).
3. *(Secondary, out of scope here)* Multiple signature fields side-by-side scale individually, causing uneven heights.

---

## Agreed Solution

> **"Height stays fixed. Text stretches horizontally. Beyond a certain character limit, truncate with '...'"**  
> *(Original: "Höhe bleibt fix. Text dehnt sich horizontal aus. Ab einem bestimmten Limit wird mit '...' abgekürzt.")*

### Rationale

- The signature field dimensions are **fixed** (`1.77" × 1.96"`). Allowing text to wrap causes position and date rows to collide vertically.
- Truncating long strings with ellipsis (`...`) keeps the layout deterministic and prevents overflow.
- Per-field max-length limits allow tuning each text row independently (name, certificate, position, city, date).

---

## Implementation Plan

### 1. `PDFBurnerParams.vb` — Add per-field max-length dictionary

Add a new property `TextMaxLengths` that maps each field name (matching `EGName` keys) to a maximum character count.

```vbnet
' EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurnerParams.vb

Public Property TextMaxLengths As New Dictionary(Of String, Integer) From {
    {"name",      28},
    {"position",  32},
    {"city",      24},
    {"date",      28}
}
```

Default values are starting points and should be tuned against real customer data.

### 2. `PDFBurner.vb` — Add truncation helper and apply in `AddFormFieldValue`

#### 2a. Add a private helper function

```vbnet
Private Function TruncateText(value As String, fieldName As String) As String
    If String.IsNullOrEmpty(value) Then Return value

    Dim maxLen As Integer = 0
    If _pdfBurnerParams.TextMaxLengths IsNot Nothing AndAlso
       _pdfBurnerParams.TextMaxLengths.TryGetValue(fieldName, maxLen) AndAlso
       maxLen > 0 AndAlso value.Length > maxLen Then
        Return value.Substring(0, maxLen - 3) & "..."
    End If

    Return value
End Function
```

#### 2b. Apply truncation in the `egName`-aware overload

In `AddFormFieldValue(pAnnotation As Annotation, formFieldValue As FormFieldValue)`:

```vbnet
' Before passing value to AddTextAnnot, truncate:
Dim displayValue As String = TruncateText(formFieldValue.value, pAnnotation.egName)

Dim ant = Manager.AddTextAnnot(oX, oY, oWidth, oHeight, displayValue)
```

#### 2c. Apply truncation in the element-based overload (optional)

In `AddFormFieldValue(x, y, width, height, page, value)` — if a field name is available in calling context, pass it through; otherwise this path does not use `egName` and truncation can be skipped or applied with a generic fallback key.

---

## Affected Files

| File | Change |
|------|--------|
| `EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurnerParams.vb` | Add `TextMaxLengths As Dictionary(Of String, Integer)` |
| `EnvelopeGenerator.CommonServices/Jobs/FinalizeDocument/PDFBurner.vb` | Add `TruncateText()` helper; apply in `AddFormFieldValue` overloads |

---

## Notes

- Field names (`"name"`, `"position"`, `"city"`, `"date"`) must match the keys used in `EGName.Index` dictionary (`PDFBurner.vb:443–450`).
- The certificate hash field (e.g. `C6B85E96A520C60...`) is already truncated upstream — verify its `egName` mapping if it needs its own limit.
- The `YOffset` / `TopMargin` values in `PDFBurnerParams` may also need adjustment to increase vertical spacing between rows. That is a separate (simpler) change.
- This issue is **not** related to the Blazor WebUI rendering — it is purely in the GdPicture14 PDF burning pipeline.