feat(web/ksef): rebuild FA(3) preview to mirror the official KSeF visualization

[norbert-kulus-blockydevs]

What

Rebuilds the FA(3) preview component (apps/web/src/plugins/ksef/components/ksef-fa3-view.tsx) so it mirrors the official KSeF/MF invoice visualization instead of the old flat slot-row list.

Two parser bugs fixed

• Swapped P_1/P_2: the parser read invoiceNumber = P_1 and issueDate = P_2, while FA(3) defines P_1 = issue date and P_2 = invoice number (the builder emits them correctly). The preview showed the date as the invoice number and vice versa. Regression-tested with a builder-shaped fixture.
• Wrong name element: the parser read NazwaSkrocona, but the builder emits Nazwa (FA(3) DaneIdentyfikacyjne) - seller name rendered as "-" and B2C buyers disappeared entirely. Now reads Nazwa with NazwaSkrocona fallback for foreign documents.

Parser extensions

Podmiot1/Podmiot2 addresses (AdresL1, AdresL2, KodKraju), KodWaluty, P_6 (sale date), P_8A (unit), P_9A (net unit price), RodzajFaktury, Platnosc (TerminPlatnosci date or TerminOpis, FormaPlatnosci code, RachunekBankowy/NrRB), PrzyczynaKorekty + corrected-invoice number from DaneFaKorygowanej/NrFaKorygowanej. VAT bands now cover the builder's full P_13_x/P_14_x set (23/8/5, 0 KR/WDT/EX, zw, np I/II, oo).

Layout (theme-aware, tokens only)

• Header: invoice number (P_2), subtitle from RodzajFaktury ("Standard invoice" / "Correction invoice"), KSeF number when present
• Two-column Seller/Buyer blocks with NIP and address
• Details row: issue date, sale date (when present), currency
• Line-items table # / Description / Net unit price / Qty / Unit / VAT rate / Net total / Gross total; gross derived at render (net * (1 + rate), non-numeric bands like zw render gross = net); VAT rate displayed with %. The Unit and Net unit price columns render only when at least one current line carries them, so documents issued before the backend emitted P_8A/P_9A get no dash-only columns
• VAT summary per band with net / tax / gross columns, then "Total due" with the currency code
• Payment section when Platnosc is present - form label from the 1-7 FormaPlatnosci map ([FEATURE] Integration — emit FA(3) Platnosc (payment method, bank account, payment term, skonto) in KSeF invoices #1311 vocabulary), payment term, bank account
• KOR: correction reason + corrected-invoice number; StanPrzed=1 "before" rows stay in the separate collapsed section ([TECH-DEBT] Invoicing correction issuance must stamp a distinct document number from the original #1364 behavior preserved)
• Skipped by design: Adnotacje (P_16-P_23), WZ, amount-in-words, generator footer
• CSS: scoped .ksef-fa3-view__* classes in apps/web/src/index.css under a bounded section comment, design tokens only (no new tokens), ~800px centered document container

How to test

• pnpm --filter @openlinker/web exec vitest run ksef-fa3-view ksef-invoice-detail-section - 29 tests pass (fixtures: full plain invoice, minimal legacy document, KOR with before-lines, payment mapping, parse-failure contract)
• pnpm --filter @openlinker/web type-check and pnpm --filter @openlinker/web lint - clean (0 errors)
• node scripts/check-design-tokens.mjs - passes
• Manually: open an issued KSeF invoice detail and click "View" on the FA(3) document row; verify the document renders correctly in both light and dark themes

Closes #1526

🤖 Generated with Claude Code

[piotrswierzy]

Tech Lead Review — PR #1528

Verdict: APPROVE. A clean, well-scoped, thoroughly-tested FE rebuild of the KSeF FA(3) preview that fixes two real correctness bugs and respects every architectural boundary. No blockers.

What it does

Rebuilds KsefFa3View (parser + render) to mirror the official KSeF/MF invoice visualization instead of the old flat slot-row list, and fixes two parser bugs: the swapped P_1/P_2 (issue-date ↔ invoice-number) mapping and the wrong name element (NazwaSkrocona → Nazwa with a foreign-doc fallback). Extends the parser to party addresses, currency, sale date, unit/net-unit-price, RodzajFaktury, Platnosc, and KOR correction metadata; adds a document-styled, theme-aware, tokens-only layout in a bounded index.css section.

Assessment

• Plugin seam — correct. The FA(3) preview renders through the KSeF plugin's invoiceDetailSection contribution (ksef-invoice-detail-section.tsx → KsefFa3View), consistent with the content-only PlatformContribution contract in frontend-architecture.md. Zero platformType === literals; all cross-boundary imports go through shared/* and features/invoicing public barrels — no deep subpaths, no host internals.
• State ownership — correct. Server state stays in the features/invoicing TanStack-Query hooks; the component only transforms already-fetched XML client-side via DOMParser (memoized on xmlText). No raw fetch().
• Types — clean. No any; explicit return types throughout; every optional FA(3) field modeled as | null (no zod snapshot .optional()/.nullish() trap — there is no zod schema here, the XML projection is hand-typed correctly).
• UI/style — compliant. Tokens only (--space-*, --text-*, --border-*, --status-*, --radius-*, --shadow-focus), no raw hex; responsive (overflow-x:auto table wrap, auto-fit party grid, flex-wrap); mono-text for ids/NIP/bank/KSeF number, tabular for amounts/dates; native <details>/<summary> with a :focus-visible ring for the KOR before-lines. check-design-tokens.mjs reported passing.
• Naming/tests — compliant. kebab-case files / PascalCase exports, *.test.tsx. 29 tests cover loading/placeholder path plus full invoice, minimal legacy doc, KOR before/after separation (#1364 preserved), payment mapping, namespace-prefixed (tns:) docs, and the parse-failure null contract.

BLOCKING

None.

IMPORTANT

None.

SUGGESTION

• ksef-fa3-view.tsx:304 (+ VAT table at :521) — add scope="col" to <th> cells for stronger screen-reader header association (a11y, frontend-ui-style-guide.md).
• ksef-invoice-detail-section.tsx:248 — fetched-but-unparseable XML yields an empty preview (chip only) instead of the placeholder/error copy, since the branch mounts KsefFa3View whenever viewText !== null and the view self-nulls on parse failure. Unlikely edge given the robust parser; pre-existing wiring (only the ksefNumber prop was added).

Positives

• Fixes two genuine data-fidelity bugs (P_1/P_2 swap, Nazwa) each with a targeted regression test.
• Namespace-agnostic localName lookup handles tns:-prefixed real-world FA(3) documents where getElementsByTagName would silently return nothing — well reasoned and tested.
• Compile-time exhaustiveness on FormaPlatnosci via a Record<KsefFormaPlatnosci, …> keyed off the guarded #1311 vocabulary, with graceful raw-code fallback for future codes.
• Per-table conditional Unit/Net-unit-price columns avoid dash-only columns on legacy documents — a thoughtful touch, tested on both plain and KOR tables.

[piotrswierzy]

SUGGESTION (a11y, frontend-ui-style-guide.md — a11y): the <th> column headers here (and the VAT-summary table at line 521) omit scope="col". For data tables, adding scope="col" gives screen readers an explicit header-to-cell association. Cheap and improves the semantics of both tables. Non-blocking.

[piotrswierzy]

SUGGESTION (UX edge case): KsefFa3View returns null when the fetched XML can't be parsed, but this branch renders <KsefFa3View> whenever viewText !== null. So a fetched-but-unparseable document shows an empty preview area (just the doc-preview__chip) rather than falling through to the fa3PreviewPlaceholder/error copy — which contradicts the "parent falls through to the placeholder" contract described in the KsefFa3View header doc. Given the parser is namespace-tolerant and well-tested against the builder's shapes this is an unlikely edge, but consider surfacing the placeholder/error text when viewText is present yet unparseable. Non-blocking, and the parse-fallback wiring predates this PR (only the ksefNumber prop was added on this line).

[norbert-kulus-blockydevs]

Addressed both SUGGESTIONs in 52bdf8f:

• a11y (ksef-fa3-view.tsx:304, :521) — added scope="col" to the line-items and VAT-summary table headers.
• UX edge case (ksef-invoice-detail-section.tsx:248) — KsefFa3View now accepts an optional onParseError callback, fired from an effect when the XML can't be parsed. KsefInvoiceDetailSection uses it to fall through to the "Preview failed" copy instead of leaving an empty preview area for a fetched-but-unparseable document. Added regression tests on both sides (child calls the callback; parent shows the fallback copy).

Not rebasing onto main yet per plan - waiting until #1523 merges first.