# StatementDocument

## 2026-08-11 - Verification block, QR code and public verify page

**Prompted by:** Clint Howen (COMPANY-503 refinement, third pass)

### What changed
- `StatementComplianceFooter` gains `verifyUrl` and `verifyQrNode`. When both
  are supplied the left panel closes with a "Check this statement is genuine"
  block: the scannable code, the verify URL, and a line stating that the check
  confirms issuer and integrity but shows no balances or transactions.
- The QR encodes `https://<verifyUrl>/<verificationReference>`, so it is unique
  per document without introducing a second identifier. The reference already
  printed in the compliance grid remains the manual fallback.
- The design system does not generate the code. `verifyQrNode` is a slot the
  consumer fills, matching the existing `qrCodeNode` convention on
  `TwoFASetupForm`, so no QR dependency enters the published package. Storybook
  supplies its own encoder in `apps/docs/stories/_shared/qr-matrix.ts`.
- New template `StatementVerifyResult`: the public page a recipient lands on
  after scanning. Three states, `verified`, `not-found` and `superseded`, each
  showing provenance (institution, product, masked account, period, issued to
  and by, generated timestamp, page count, content fingerprint) and never
  balances, transactions or a full account number.

### Why
- The verification reference was previously printed with nothing behind it. A
  reference a recipient cannot check is decoration; it needs a public page and
  a scannable route to that page to mean anything.
- Statements are the document class most often forged in lending, so the
  verification path is the anti-tamper story for a broker-facing artefact.
- The verify page is read by whoever holds the PDF, not an authenticated user,
  so it confirms authenticity without disclosing financial detail.

### Affected tokens / files
- `packages/shadcn/src/components/ui/statement-primitives.tsx`
- `packages/shadcn/src/components/ui/statement-verify-result.tsx`

## 2026-08-11 - Compliance footer layout and printed links

**Prompted by:** Clint Howen

### What changed
- The verification block moved out of the CDR prose panel into its own
  full-width band between the provenance grid and the disclaimer strip. In the
  narrow left column its copy wrapped into a tall ragged stack; across the full
  page width it sets on two lines beside the QR.
- New `StatementLink` atom: an anchor underlined in the document's own ink
  rather than a theme colour, so it stays legible printed in black and white
  while still resolving when the PDF is read on screen.
- The verify URL is now a link, and the issuer website (`websiteUrl`) prints as
  a link at the right of the disclaimer strip.

### Why
- The verification band is the one part of the footer a recipient is meant to
  act on, so it needs the full measure rather than the residue of a column.
- A printed statement is read both on paper and on screen; the links have to
  work in the second case without shouting in the first.

### Affected tokens / files
- `packages/shadcn/src/components/ui/statement-primitives.tsx`

## 2026-08-09 - CDR compliance footer and multi-page statements

**Prompted by:** Clint Howen (COMPANY-503 refinement, second pass)

### What changed
- New `StatementComplianceFooter` atom replicating the samples' Consumer Data
  Right provenance block: explanatory paragraphs left, a bordered grid of
  data holder / data recipient / service provider / verification reference
  cells right, and the grey disclaimer strip underneath. Rendered on the last
  page of the statement via the template's `compliance` prop;
  `consentProvidedBy` defaults to the holder name.
- New `paginate` prop ({ firstPageRows, rowsPerPage }) splits the ledger
  across multiple A4 pages: page one carries the summary blocks plus the
  first rows, continuation pages open with a "Balance brought forward" row,
  and the closing balance plus compliance block print on the last page. Page
  footers number as "Page N of M".
- All em and en dashes removed from statement copy, mocks and docs; the
  statement period and footer reference use plain hyphens as the samples do.
- Header now renders the institution logo (h-10, left aligned under the title)
  with the institution name printed below it, matching the samples where the
  bank appears both as a mark and named in copy (and again as the Accredited
  Data Holder in the compliance block). Story mocks use Basiq's own logo
  artwork, copied from its public institutions endpoint
  (`logo.links.full`, e.g. `https://d388vpyfrt4zrj.cloudfront.net/AU04301-full.svg`)
  into `apps/docs/public/banks/*-basiq.svg`: Commonwealth Bank for transaction,
  savings and credit card; NAB for business and personal loan; Macquarie for
  mortgage and offset. At runtime the app passes the CloudFront URL straight
  into `institutionLogo`. The compliance block's Accredited Data Holder is
  matched to the statement's institution.

### Why
- The samples close every statement with the CDR provenance block; the first
  refinement pass had left it out.
- Real statements over 3 to 12 month windows run past one page; the design
  needs to show how the document behaves at that length.

### Affected tokens / files
- `packages/shadcn/src/components/ui/statement-primitives.tsx`
- `packages/shadcn/src/components/ui/statement-document.tsx`

## 2026-08-09 - Field sets and page grammar aligned to the Open Banking samples

**Prompted by:** Clint Howen (COMPANY-503 refinement pass against the `Sample_Open_Banking_statement_*` PDFs on COMPANY-501)

### What changed
- Page restructured to the sample grammar: header → holder + identity block →
  balances + detail block → linked offset block (mortgage with offset) → ledger →
  ruled page footer with "Generated on". The statement period moved into the
  identity block; the meta band atom was replaced by `StatementPageFooter`.
- Identity block is now identical for every account type: product name, account
  BSB (omitted for credit cards), account/card number, account type, product
  category, account status, account opened date, statement period.
- Balance block gains Total credits and Total debits (computed from the ledger),
  plus Max redraw on mortgages and Credit limit on cards.
- Detail fields transcribed from the samples: deposit shows interest rate only;
  mortgage shows repayment type, loan start/end dates, remaining term, rate,
  rate type, fixed rate expiry, minimum repayment, frequency; a personal loan
  shows no detail column (as in the sample); credit card shows purchase and
  cash-advance rates, minimum repayment, frequency. Original loan amount, next
  repayment date and payment due date were removed - none appear in the samples.
- The ledger is one shape for every type - Date / Transaction / Debit / Credit /
  Balance. The lending Amount / Balance variant was removed; loan and card
  balances print signed negative, repayments as credits, interest charges as
  debits, exactly as the samples do.
- Linked offset block reworked to the sample's fields: financial institution,
  account name, BSB, account number, account category. "Interest saved" was
  removed (not in the sample); the offset balance is carried by the loan's
  Available balance row.
- Missing values print "Not available" (muted) instead of an em dash.
- Business-account statements carry Legal name / Agent name / ABN under the
  holder address.

### Why
- The PRD's answer on COMPANY-501 ("the style we want to replicate as the data
  points shown is linked to the type of account") makes the sample PDFs the
  field-list source of truth. The first pass derived fields from the app's old
  template; this pass transcribes them from the samples.

### Affected tokens / files
- `packages/shadcn/src/components/ui/statement-document.tsx`
- `packages/shadcn/src/components/ui/statement-primitives.tsx`
- `packages/shadcn/src/components/ui/statement-transaction-table.tsx`

## 2026-08-09 - Statement layout now varies by account type

**Prompted by:** Clint Howen (COMPANY-501 / COMPANY-503), design routine first pass

### What changed
- New template. Previously the app rendered one PDF layout for every account type.
- Seven account types map to three layout families via `ACCOUNT_TYPE_LAYOUT`:
  `deposit` (transaction, savings, business transaction), `lending` (mortgage,
  mortgage with offset, personal loan), `credit` (credit card).
- Deposit statements show BSB, account number, date opened, interest rate, opening
  balance, available funds, closing balance - and a Debit / Credit / Balance ledger.
- Lending statements show loan start and maturity dates, original amount, lending
  rate, repayment type / frequency / minimum, next repayment, available redraw, and
  balance owing - with an Amount / Balance activity table instead of a ledger.
- Mortgage with offset adds a linked-offset block (offset account, balance, interest
  saved this period).
- Credit-card statements show credit limit, available credit, purchase and cash-advance
  rates, minimum payment due, and balance owing, with the payment due date carried in
  the statement meta band.
- The page renders on fixed white paper with fixed ink colours in both light and dark
  mode; the tenant logo slot is the white-label surface.

### Why
- A mortgage statement previously showed an empty transaction ledger beside loan fields,
  and a savings statement showed seven `-` rows of loan fields. Every field on a page now
  belongs to that kind of account, matching how banks actually issue statements.
- Three families rather than seven bespoke templates keeps ~80% shared field logic in one
  place; the type → layout map means adding an account type is a one-line change.
- A statement is a printed artefact - it stays white paper in dark mode, as it would on paper.

### Affected tokens / files
- `packages/shadcn/src/components/ui/statement-document.tsx`
- `packages/shadcn/src/components/ui/statement-primitives.tsx`
- `packages/shadcn/src/components/ui/statement-transaction-table.tsx`