Bank report wizard: editable HTML preview before export

[steilerDev]

As a homeowner about to send a report to my bank, I want to edit the report's wording — the table's descriptive text and the whole cover letter — directly in the preview before exporting so that I can correct or tailor anything the generated text got wrong without leaving the wizard or hand-editing a PDF.

Part of the Bank Report Wizard — Refinement Round 2 mini-epic. Source: direct user verification of the merged wizard. Scope decomposed and approved during mini-epic planning.

Priority: Must Have
Blocked by: #1898 (report table refinements), #1899 (settings step + report language)
Blocks: #1901 (AI generation)

Settled decisions (do not re-litigate): Step 5 is an HTML edit surface with on-demand PDF — there is no live side-by-side PDF pane. "Letterhead" means the full cover letter: sender, recipient, reference, subject, and body blocks are all editable. Amounts and totals stay read-only because they are derived.

---

Acceptance Criteria

1. Editable report content in Step 5

• Given I reach Step 5 "Preview & Export", when it renders, then it shows the full report content as editable HTML rather than only a rendered PDF frame.
• Given the editable report table, when it renders, then it shows one row per included invoice with the report's columns: vendor, invoice number, date, status (only where the report type keeps it, per Bank report: Usage column, attachment notes, deposit footnote & column cleanup #1898), usage text, attachments note, and amounts.
• Given invoices excluded in Step 3, when the editable table renders, then they are absent from it — the editable content reflects the Step-3 selection and line exclusions exactly.
• Given the "include cover letter" option is on, when Step 5 renders, then the complete cover letter is shown with separately editable fields for sender, recipient, reference, subject, and body.
• Given the "include cover letter" option is off, when Step 5 renders, then no cover-letter fields are shown and no cover letter is exported.
• Given the editable surface, when I use only a keyboard, then every editable field is reachable, has an accessible label, and shows a visible focus indicator; the surface works at desktop, tablet, and mobile viewports.
• Given the editable surface, when it renders, then it uses design tokens and existing shared components — no hardcoded colours, spacing, radii, or font sizes — and renders correctly in dark mode.

2. What is editable vs. read-only

• Given any wording/text field in Step 5 (usage text, attachments note, and every cover-letter block), when I click into it, then I can edit it freely.
• Given any amount cell (per-invoice invoice amount and allocated amount), when I attempt to edit it, then it is read-only — it cannot be typed into, and it is visually and programmatically marked as non-editable.
• Given any total or subtotal cell, when I attempt to edit it, then it is read-only, and its value continues to be derived from the Step-3 selection and exclusions.
• Given read-only amounts, when the report is exported, then the exported figures are byte-for-byte the derived values — no user input path can alter a number.

3. Baseline, regeneration, and warning

• Given I first arrive at Step 5, when the editable content renders, then it is populated from a generated baseline (the same content the report would produce today, in the language chosen in Step 4).
• Given I have made edits and I go back and change something in Steps 1–4 (report type, source, invoice/line selection, report language, or the export toggles), when I return to Step 5, then the baseline is regenerated and my edits are cleared.
• Given I have unsaved edits and I attempt a Step 1–4 change that would regenerate the baseline, when I trigger it, then I am shown an explicit confirmation warning that my edits will be lost, and I can cancel to keep them.
• Given I have made no edits, when I change something in Steps 1–4, then no warning is shown (the warning only appears when there is something to lose).
• Given I confirm the regeneration, when Step 5 re-renders, then the content matches a freshly generated baseline with no residue of the discarded edits.
• Given edits are modelled as overrides on a generated baseline, when a field is untouched, then it continues to track the baseline (it is not silently frozen at the first render).

4. On-demand PDF

• Given Step 5, when it renders, then there is no continuously regenerating background PDF and no live PDF pane — the PDF is produced only on demand.
• Given Step 5, when I trigger the "Preview PDF" action, then a PDF is generated from the currently edited content and shown to me.
• Given I have edited content, when I download the report, then the produced PDF reflects every edit I made.
• Given I have edited content, when I upload to Paperless, then the uploaded PDF reflects every edit I made.
• Given I have edited content, when I trigger mark claimed, then the PDF generated for that flow reflects every edit I made, and the mark-claimed behaviour itself (including the excluded-lines warning from Bank report wizard follow-up: blob: CSP for preview, status chip sizing, expandable invoice rows & deposit budget source #1891) is unchanged.
• Given the PDF preview, when it renders, then it displays actual content in the frame — the assertion is that the frame renders, not merely that a blob: URL was assigned (the CSP regression class from Bank report wizard follow-up: blob: CSP for preview, status chip sizing, expandable invoice rows & deposit budget source #1891 must not reappear).
• Given a PDF generation failure, when it occurs, then the error is surfaced to me clearly and my edited content is preserved.

5. Translations

• Given every new user-facing string (labels, the regeneration warning, the Preview PDF action, read-only affordances), when it renders, then it comes from t() and resolves in both en and de.
• Given the wizard chrome vs. report content, when both render, then the chrome follows the UI locale and the report content follows the Step-4 report language (per Bank report wizard: Settings step with report language selection #1899).

---

Out of scope

• AI-generated text — that is Bank report wizard: AI-generated usage descriptions and cover letter #1901. This story only makes the fields editable and wires the on-demand PDF; the baseline here is the deterministic, derived text from Bank report: Usage column, attachment notes, deposit footnote & column cleanup #1898.
• Persisting edited reports server-side, saving drafts, or re-opening a previously edited report.
• Rich-text formatting controls (bold/italic/lists) in the editable fields — plain wording edits only unless the dev-team-lead's spec establishes otherwise.
• Editing amounts, totals, or the invoice selection from Step 5 — selection stays in Step 3.

Notes

• Step 5 surface: client/src/pages/ReportWizardPage/, client/src/components/reports/ReportPdfPreview.tsx, ReportInvoiceList.tsx.
• PDF pipeline: client/src/lib/reportPdf/ — today overviewPdf.ts / coverLetterPdf.ts build content directly from the report response. This story inserts an intermediate, editable content model between the response and the PDF builders; the builders must consume that model so preview and every export path share one source.
• Derived-amount contract facts still apply: allocatedAmount is negative for lineKind: 'refund-adjustment' (never re-negate), and report.totalAmount is not the grand total once invoices are excluded — the included total comes from merge.ts.
• Testing: extend realRender.test.ts to assert that an edited baseline reaches the rendered PDF and that excluded rows stay out of the totals. Any "preview renders" assertion must check rendered content, not a src attribute.

[steilerDev]

[ux-designer] Visual specification for Step 5's editable HTML report surface.

Read: issue #1900 acceptance criteria, client/src/pages/ReportWizardPage/ReportWizardPage.tsx (5-step wizard, confirmed post-#1899), Step5Actions.tsx, components/reports/ReportPdfPreview.tsx, ReportInvoiceList.tsx (+ .module.css), client/src/lib/reportPdf/{overviewPdf,coverLetterPdf}.ts, WorkItemDetailPage inline-edit pattern, AutoItemizePage discard-confirm pattern, client/src/styles/{tokens.css,shared.module.css}.

---

Component Mapping

UI Element	Shared Component	Props/Variant	Notes
Single-line editable field (usage text override on desktop table row is short; subject, reference, sender lines)	NEW EditableField	as="input", ariaLabel, value, onChange, isEdited, onReset	New shared component — see justification below
Multi-line editable field (cover letter body, attachments note, footnotes)	NEW EditableField	as="textarea", rows, same props	Same component, textarea variant
Read-only amount/total/subtotal cell	(none — plain text)	—	Deliberately not a form control; see item 2
Discard-edits confirmation	Modal	title + sharedStyles.btnPrimary/btnSecondary footer	Existing — reuse AutoItemizePage "Discard Changes?" pattern verbatim
On-demand PDF preview	Modal (wide className override) + existing ReportPdfPreview	unchanged internals	Existing — Modal's documented "local override to adjust max-width" pattern (shared.module.css .modalContent comment)
Skip/split/deposit footnotes	(none — plain text list)	—	Already exists in PDF; now also rendered as read-only HTML list, unchanged treatment
Desktop table / mobile cards for invoice rows	Existing responsive pattern from ReportInvoiceList	.tableWrapper + .mobileCardList at max-width: 767px	Reuse the exact breakpoint and markup shape, extended with editable cells

Why a new shared component (EditableField) is warranted

I checked WorkItemDetailPage's inline-edit pattern (isEditingTitle/isEditingDescription) first, since it's the only existing "editable field in a detail-style page" pattern in the app. Do not reuse it — it's a different interaction paradigm: hidden static text until click, an explicit Save/Cancel pair, and a direct API persist per field. Step 5's fields are the opposite: always rendered as inputs (no click-to-reveal), there is no per-field Save — every keystroke is an ambient override on the in-memory baseline, and persistence only happens implicitly when an export action runs. Forcing WorkItemDetailPage's pattern here would require Save/Cancel affordances the acceptance criteria never describe and that fight the "type freely" requirement.

No existing shared component covers "always-editable text/textarea with a baseline-diff indicator and per-field reset." Per the Component Reuse Policy this must become one new shared component (client/src/components/EditableField/), not a page-local implementation, so it's available for future report/wizard work. It takes an as="input" | "textarea" prop, wraps the existing .input/.textarea classes from shared.module.css (don't reinvent field chrome — compose the shared base and add only the at-rest/edited-state layer described in item 2), and centralizes the edited-dot + reset-button treatment so table cells and letter blocks look identical.

---

1. Layout

Drop the .step4Layout two-column options|preview grid for step 5 entirely — a real <table> and a full letter need the full content width, and a side-by-side PDF pane no longer exists per the settled decision. New structure, top to bottom, all full-width inside the existing .metadataCard:

1. Step heading (unchanged pattern).
2. Cover letter block (only when includeCoverLetter is on) — a bordered card (reuse the .settingsCard treatment: var(--color-bg-secondary), 1px solid var(--color-border), var(--radius-lg), var(--spacing-4) padding) containing the five EditableFields stacked vertically with labels: Sender, Recipient, Reference (optional — omit the field entirely when the source has no reference/contact address, matching today's conditional PDF rendering, not just disable it), Subject, Body.
3. Report table — a real <table>, one <thead> + one <tbody><tr> per included invoice, columns per Bank report: Usage column, attachment notes, deposit footnote & column cleanup #1898/overviewPdf.ts: Vendor (read-only, already a fact not wording), Invoice No. (read-only), Date (read-only), Status badge (overview only, read-only — reuse Badge exactly as ReportInvoiceList does), Usage text (EditableField as="input"), Attachments note (EditableField as="input"), Invoice Amount (read-only), Allocated Amount (read-only). Subtotal/total rows stay plain text rows, no inputs at all.
4. Footnotes — plain read-only list under the table (skip/split/deposit markers */†/‡), matching overviewPdf.ts footnote text.
5. Actions bar — Step5Actions, ported as-is but now full-width below the content (not a second grid column). Add the "Preview PDF" action as the first, leftmost button in that row, styled btnSecondary (it's a non-committing preview, not an export), with a document/eye icon consistent with the FormError/EmptyState icon convention. Download / Mark Claimed / Upload Paperless keep their existing order and styling immediately after it.

No separate "options" panel remains in step 5 — Step 4 already owns attachDocuments/includeCoverLetter/language, so nothing is lost.

On-demand PDF surface: recommend Modal, not an inline collapsible. Reasoning: the acceptance criteria explicitly forbid "a live PDF pane," and a collapsible would visually re-introduce one once expanded (plus it competes for the same vertical space as the editable content the user is actively scanning). A Modal cleanly frames the PDF as a distinct, dismissible "preview," matches the existing .modalContent "local override to adjust max-width per dialog type" convention already documented in shared.module.css, and reuses ReportPdfPreview's existing iframe/spinner/error/retry internals unchanged inside the modal body. Use a wide className override (recommend max-width: 50rem — wide enough to read an A4-proportioned PDF, still short of full-bleed). Footer: single btnSecondary "Close" button; the page's own Download button remains the actual save action, so don't duplicate it in the modal footer.

Operational note for the spec-writer: since there's no more persistent previewBlob kept warm in the background, Download / Mark Claimed / Upload Paperless must each trigger their own on-demand PDF generation from the current edited content at click time (not rely on a pre-generated blob). Each of those three buttons needs a busy/loading state (spinner + disabled, same visual treatment ReportPdfPreview's Spinner already uses) for the moment between click and file-ready, since generation is no longer instantaneous-from-cache.

---

2. Editable field treatment (EditableField)

At rest (has focus neither via mouse nor keyboard): a subtle affordance only — border: 1px solid transparent, background-color: var(--color-bg-tertiary) at low visual weight so it reads as "this text lives in a field" without looking like an error or a heavy input box sitting in a dense table row. No visible border color at rest; the tinted background is the sole idle signal. This deliberately differs from the standalone .input/.textarea classes (which show a full 1px solid var(--color-border-strong) border) because a table full of bordered boxes at every cell reads as noisy — same reasoning ReportInvoiceList's table already uses borderless-until-hover rows.

Hover: background-color: var(--color-bg-secondary) (one step lighter/darker than at-rest, matching the existing .invoiceRow:hover treatment) — signals "clickable" before the user commits to editing.

Focus: outline: none; border-color: var(--color-primary); box-shadow: var(--shadow-focus-subtle) inside dense table cells, and var(--shadow-focus) (the stronger ring) for the full-width letter-block fields — same subtle/strong split the app already uses between compact list rows (inset ... box-shadow treatments) and standalone form inputs (.input:focus-visible uses --shadow-focus-subtle). Never outline: 2px solid ... — always the shared box-shadow focus-ring tokens (see my memory notes on the recurring outline-vs-box-shadow bug).

Read-only amount/total/subtotal cells: render as plain text (<td>{formatCurrency(...)}</td>, no wrapping <input>, no contentEditable) using the existing .amount typography (font-weight: var(--font-weight-medium), var(--font-size-sm)). This is the "programmatic" non-editable marking the AC asks for — there is no form control present at all for a screen reader or a Tab stop to land on, so nothing needs an explicit aria-readonly (that attribute only has meaning on actual form controls). Visually, pair this with the absence of the tinted background/border affordance described above — sitting directly beside an editable cell with a visible background tint, an untinted plain-text cell reads as "not this one" without extra decoration. Do not grey out or dim the amount text — it's not disabled, it's simply not a field.

Textarea sizing: fixed rows per field (body: rows={6}, attachments note / usage text if ever multi-line: rows={2}), resize: vertical — reuse .textarea behavior exactly (no JS auto-grow; the app has no existing auto-height textarea pattern and this story doesn't need to invent one).

Table cell input sizing: inside the real <table>, EditableField as="input" fills the cell (width: 100%, box-sizing: border-box), with tighter padding than the standalone .input (var(--spacing-1) var(--spacing-2) vs. .input's var(--spacing-2) var(--spacing-3)) to keep row density close to ReportInvoiceList's existing .table td { padding: var(--spacing-2) var(--spacing-3); }. On desktop this is intentionally more compact than the 44px touch-target minimum — that's acceptable because desktop pointer precision doesn't require it, and the mobile card layout (item 4) gives every field its own full-width row with proper touch sizing instead.

---

3. Edited-state indicator

Keep it minimal, per the ask: a small dot, not a badge with text, not a color change on the whole field.

• Dot: a 0.375rem circle, background-color: var(--color-primary), positioned absolute at the field's top-right corner (top: -2px; right: -2px), aria-hidden="true" — purely decorative, the accessible signal is separate (see below). Fades in with transition: opacity var(--transition-fast), respecting prefers-reduced-motion: reduce (skip the fade, same convention as the existing .chevron transition guard in ReportInvoiceList.module.css).
• Screen-reader equivalent: don't rely on the dot. Append " (" + t('sourceReports.editable.editedSuffix') + ")" — e.g. "(edited)" — to the field's aria-label when it has an override, so the edited state is announced on focus without a separate live region (a live region firing on every keystroke would be noisy and is not warranted here — this isn't dynamic content arriving asynchronously).
• Per-field reset: a small icon-only button (undo/counter-clockwise-arrow icon, reuse the compact icon-button sizing from .clearDateButton in WorkItemDetailPage.module.css — padding: 0 var(--spacing-1), color: var(--color-text-muted), hover color: var(--color-text-primary)), shown only when the field has an override, positioned after the field (same inlineFieldWrapper flex-row shape). aria-label={t('sourceReports.editable.resetFieldAriaLabel', { field: <column/label name> })}. Clicking it clears just that field's override back to the current baseline value — this is the "reset-per-field affordance" the issue asks about, and it's what makes the page-level regeneration warning tolerable (users have a lightweight undo before reaching for the nuclear option).

Regeneration/discard confirmation: reuse the exact pattern already shipped in AutoItemizePage.tsx for "Discard Changes?" (t('autoItemize.cancelConfirmTitle')/cancelConfirmBody) rather than inventing a new visual language or borrowing the amber .warningBlock treatment (that's reserved for the informational sub-warning already used inside the claim-confirm modal on this same page, not for the primary confirm dialog itself). Concretely: Modal with title={t('sourceReports.editable.discardConfirmTitle')}, body t('sourceReports.editable.discardConfirmBody'), footer with sharedStyles.btnPrimary "Discard and Continue" (matches AutoItemizePage's discard-action-first ordering) then sharedStyles.btnSecondary "Keep Editing"/Cancel. Only trigger it when at least one field has an override (per AC #3's "no edits = no warning" rule) — gate the Step 1–4 navigation/change handlers on an isDirty-style check, same naming convention already used in AutoItemizePage.tsx (isDirty, hasUnsavedChanges-style flag).

---

4. Responsive

Report table: reuse ReportInvoiceList's established desktop-table / mobile-card split at the same breakpoint (max-width: 767px, i.e. below --breakpoint-md) — don't introduce a different breakpoint for this table. Mobile card per invoice: vendor + invoice number as the card heading row (existing .mobileCardTopRow shape), status badge (overview only), then each editable field gets its own full-width labeled row (.mobileCardRow with a visible text label above the field, not just an aria-label) — on mobile there's no dense table row to imply the column header, so the label must be visible text, not just programmatic. This also naturally gives each EditableField full 44px+ touch height on mobile, resolving the desktop-density trade-off from item 2. Amount cells stay plain read-only text rows, same as desktop.

Cover letter block: already a natural single-column stack at all viewports (it's not tabular) — just ensure each EditableField is width: 100% and labels sit above the field (never side-by-side at any width, since sender/recipient/body content is genuinely variable-length and a label+value row would force awkward wrapping). No breakpoint-specific behavior needed here beyond normal container reflow.

Actions bar: Step5Actions already wraps (flex-wrap: wrap) in .actionsContainer/.buttonRow — the new "Preview PDF" button just joins that existing wrap behavior, no new responsive rule needed.

---

5. Dark mode + accessibility

Tokens only — every color in EditableField must route through Layer 2 semantic tokens that already flip under [data-theme="dark"]: --color-bg-tertiary, --color-bg-secondary, --color-primary, --color-border-strong, --color-text-muted, --color-text-primary, --shadow-focus / --shadow-focus-subtle. None of these need a dark-mode-specific override file edit — they already have [data-theme='dark'] redefinitions in tokens.css. Verify contrast of the at-rest tinted background against both the editable text (--color-text-primary) and placeholder text if any — --color-bg-tertiary against --color-text-primary already passes AA elsewhere in the app (used for .headerCheckbox-adjacent surfaces), no new pairing being introduced.

Label association — every EditableField needs a programmatic label, not just visible text nearby, since acceptance criteria specifically calls out "every unlabeled table-cell input" needing one:

• Letter block fields (block-level, own row): use a real <label htmlFor> associated with the input/textarea id — visible text label, standard association, no aria-label needed here.
• Table-cell fields (dense, no per-cell visible label on desktop): aria-label built from column header + row context, e.g. t('sourceReports.editable.usageTextAriaLabel', { vendor: invoice.vendorName, invoiceNumber: invoice.invoiceNumber }) → "Usage text for Acme GmbH, INV-1029" — same composition pattern ReportInvoiceList already uses for excludeItemAriaLabel. On mobile the card layout adds a visible label too (item 4), so the aria-label there becomes redundant-but-harmless (fine — don't special-case it away).
• Read-only amount cells: no control, no label needed (see item 2).

Keyboard nav: natural Tab order through the table (row by row, left to right, same as any HTML table with <input> cells — no custom roving-tabindex grid needed, this is a real table with real form controls, not a widget). Reset buttons and the header checkbox/expand-chevron pattern from ReportInvoiceList don't apply here (this table has no row-selection or expand/collapse — it's pure display + edit). "Preview PDF" opens a Modal, which already owns focus trap + Escape-to-close + return-focus-on-close per the existing Modal component — no new keyboard work required there.

Reduced motion: only the edited-dot fade (item 3) and the existing Spinner/chevron treatments are motion-bearing here; guard the dot's transition the same way .chevron already is.

---

6. Translations

New strings needed (namespace budget, prefix sourceReports.editable.* to match the existing sourceReports.expand.* sub-namespace convention):

• sourceReports.editable.senderLabel / recipientLabel / referenceLabel / subjectLabel / bodyLabel (letter block field labels — note subjectLabel/reference labels already exist under sourceReports.coverLetter.* for the generated PDF text; these are new, separate keys for the form field labels in the editable UI, don't collide the two)
• sourceReports.editable.previewPdf (button label)
• sourceReports.editable.editedSuffix (" (edited)" aria-label suffix)
• sourceReports.editable.resetFieldAriaLabel ({{field}} interpolation)
• sourceReports.editable.usageTextAriaLabel / attachmentsNoteAriaLabel ({{vendor}}, {{invoiceNumber}} interpolation)
• sourceReports.editable.discardConfirmTitle / discardConfirmBody / discardAndContinue (mirror autoItemize.cancelConfirmTitle/cancelConfirmBody/discardChanges wording pattern — reuse "Keep Editing"/common:button.cancel for the cancel side rather than a new key if wording matches exactly)

Per AC #5, wizard chrome strings (labels, the button, the warning) come from the UI locale (t()/i18n), while the editable content itself (the baseline text populating each field) is generated in reportLanguage via reportT — same split the wizard already applies to the PDF today. Confirm with the dev-team-lead spec that the baseline generation step (wherever it now lives — likely a refactor of overviewPdf.ts's row-building and coverLetterPdf.ts's block-building into the new "content model" the issue's Notes section describes) still calls reportT/reportFormatters, not the chrome t.

---

Flagging one open question for the dev-team-lead spec rather than deciding it myself: the generated PDF's signature block reuses the household name a second time after the body (coverLetterPdf.ts lines 76–83). The issue's settled decision lists sender/recipient/reference/subject/body as the five editable fields — it doesn't mention a signature field. I'd treat the signature as derived display, not independently editable (it just echoes whatever the Sender field currently contains) rather than adding a sixth field, but that's a product/architecture call, not a visual one — worth a one-line confirmation before implementation.